# MCP configuration and diagnostics

Reckon exposes exactly one MCP tool named `reckon`. Capabilities such as
context, explain, review, search, docs, doctor, repositories, and systems are
operations of that gateway, not separate top-level tools.

## Choose a scope

- **Personal:** `reckon init --scope personal` configures detected clients with
  user-owned or excluded local files.
- **Team:** `reckon init --scope team` writes merge-safe repository
  configuration for supported clients. Commit only the intended files.
- **CLI-only:** `reckon init --scope cli-only` keeps the local graph and Git
  refresh behavior without MCP registration.

Reckon supports project adapters for Claude Code, Codex, Gemini CLI, and
Antigravity. A generic MCP handshake is release-gated. Named-client status is
reported only when its adapter/configuration is detected; it is not proof of
every client version or platform.

## Canonical command

The server command is:

```text
reckon serve
```

Prefer this command when the client inherits the same PATH. If it does not,
use the absolute stable shim reported by `reckon doctor`. A mise or Volta shim
is preferable to a version-specific npm global path. nvm/fnm/asdf npm globals
can change when the selected Node version changes.

Manual JSON configuration:

```json
{
  "mcpServers": {
    "reckon-graph": {
      "command": "reckon",
      "args": ["serve"]
    }
  }
}
```

Codex TOML:

```toml
[mcp_servers."reckon-graph"]
command = "reckon"
args = ["serve"]
```

## Compact structural responses

Use `detailLevel: "compact"` for the Token Optimizer-style structural path:

- `query` with `file_summary`, `batch_outline`, or `project_overview`;
- `search` for normalized symbol-name discovery; or
- `explain` with `includeSource: true` for exact symbol source.

The response is a deterministic compact string. Its first line reports
freshness and returned/total counts; result lines retain a stable `~` identity
handle, symbol kind, nesting where applicable, and source location. Outline
rows also retain a compact signature. An ambiguous explain begins with
`ambiguous` and lists candidates instead of selecting one. A returned `~`
handle may be supplied as `identity` on a later request; prefix collisions
remain explicit ambiguity rather than becoming a guessed match.

This mode intentionally omits unrelated graph fields, generic telemetry, and
the normal response-budget envelope. `byteBudget` still acts as a hard UTF-8
ceiling by removing complete result rows and updating the returned count. When
the requested budget cannot fit even the truthful header, the result is empty
rather than exceeding the caller's limit. The full structured response remains
the default when `detailLevel` is omitted.

## Real handshake diagnostics

Run:

```bash
reckon doctor
```

Doctor resolves the executable/symlink chain, inspects duplicate candidates,
reports configured client files, and sends real JSON-RPC `initialize` and
`tools/list` requests. A healthy response identifies server
`reckon-graph` and exactly one tool named `reckon`.

If the handshake fails:

1. Run `command -v reckon` and `reckon --version` in the client's environment.
2. Check `reckon doctor` for a version-manager-owned PATH or duplicate install.
3. Re-run `reckon init` after changing the manager, Node version, or shim.
4. Inspect client logs without copying tokens, source, or personal paths into
   public reports.

MCP requests never trigger update-network checks. Cached update state is
available through the `doctor` operation without changing stdio framing.