> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/scan.md).

# observal scan

Discover MCP servers, hooks, and telemetry configuration across your harness configs. `scan` is **read-only** -- it shows what you have without modifying any files.

To install session telemetry hooks, use [`observal doctor patch`](/cli-reference/doctor.md). MCP commands and URLs are never rewritten.

## Synopsis

```bash
observal scan [--harness <harness>]
```

## Options

| Option                | Description                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--harness <harness>` | Scope to one harness: `cursor`, `kiro`, `claude-code`, `codex`, `copilot`, `copilot-cli`, `opencode`, `antigravity`, `goose`, `pi` |

If you run `observal scan` with no flags, it auto-detects every installed harness and scans each in turn.

## What it does

1. Finds MCP config files:
   * Claude Code: `~/.claude/settings.json`
   * Kiro: `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (home)
   * Cursor: `.cursor/mcp.json`
   * Copilot: `.vscode/mcp.json`
   * Antigravity: `.agents/mcp_config.json` or `~/.gemini/antigravity-cli/mcp_config.json`
   * Goose: `~/.config/goose/config.yaml` (the `extensions` key)
   * Copilot CLI: `~/.copilot/mcp-config.json`
2. Lists every MCP server found and its direct command or URL.
3. Reports installed session telemetry hooks.

No files are written. No servers are contacted. No registration happens.

## Example

```bash
observal scan
```

Output:

```
Claude Code (~/.claude/settings.json)
  filesystem        npx @modelcontextprotocol/server-filesystem   not wrapped
  github            npx @modelcontextprotocol/server-github       not wrapped

Kiro (.kiro/settings/mcp.json)
  mcp-obsidian      mcp-obsidian                                  not wrapped

2 harness(s) found, 3 MCP server(s) total, 0 wrapped.
```

## Scoping to a single harness

```bash
observal scan --harness claude-code
```

## What to do next

Once you see what's installed, instrument it:

```bash
# Install session telemetry hooks across all harnesses
observal doctor patch --all-harnesses

# Or target a specific harness
observal doctor patch --harness kiro

# Preview changes without writing anything
observal doctor patch --all-harnesses --dry-run
```

## Exit codes

| Code | Meaning                           |
| ---- | --------------------------------- |
| 0    | At least one harness config found |
| 1    | Server unreachable / auth failed  |
| 3    | No harness configs found          |

## Related

* [`observal doctor patch`](/cli-reference/doctor.md): instrument your harnesses (hooks, shims)
* [`observal agent pull`](/cli-reference/pull.md): install a full agent (also wires up MCP servers)
* [`observal doctor`](/cli-reference/doctor.md): diagnose instrumentation end-to-end
* [Use Cases -- Observe MCP traffic](/use-cases/observe-mcp-traffic.md): narrative walkthrough


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/scan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.