# MCP server

> Connect an MCP client to Estelle for repository navigation, memory, monitoring, research, reviews, and agent jobs.

Estelle's hosted MCP server gives a compatible coding agent one connection to your indexed repositories, saved sessions, production data, and Estelle workflows. Use it when you want the agent to look up real code, resume earlier work, inspect monitoring, or start a job without building those integrations yourself.

| Setting | Value |
|---|---|
| Endpoint | `https://api.fatelabs.ca/mcp` |
| Transport | HTTP |
| Authentication | Browser OAuth, or `Authorization: Bearer estelle_live_...` |

A client that supports OAuth prompts you to sign in. For a client without OAuth, create a key in **Settings → API keys** and send it as the bearer header. Keep keys out of committed configuration.

## Connect your client

For Claude Code, Codex, Kimi Code, Grok Build and Cursor, follow the [native plugin instructions](https://docs.fatelabs.ca/install). They use the public plugin repository, external Node.js 22+ and the same account key for hooks and MCP. Native installation and hook approval differ by host.

A hosted MCP-only connection gives you tools without the plugin's session hooks. Add `https://api.fatelabs.ca/mcp` using your client's HTTP server configuration. A client with browser authentication may offer sign-in; otherwise use an `Authorization: Bearer` header with your account key, stored securely by the client. Do not paste the value into a conversation or committed configuration.

Verify access with one advertised read-only tool from that session, then check session hooks separately if you installed the plugin. A server catalogue is not a session-capture receipt.

Start a new session after connecting and ask the agent to call `estelle_resume`. It returns saved context or says that none exists. Index a repository before using repository navigation; see [Install](https://docs.fatelabs.ca/install) and [Code graph](https://docs.fatelabs.ca/code-graph).

## Choose tools by task

The exact tools available depend on the connection and account. Your agent reads each tool's current argument schema, so you normally ask for the outcome in plain language rather than constructing calls yourself.

### Navigate and read code

| Tool | Use it to |
|---|---|
| `verify` | Check code or a claim against the indexed repository and identify unresolved APIs. |
| `find_definition` | Get file and line locations for a symbol. |
| `find_usages` | Find call sites before changing a function. |
| `find_references` | See which files import a file. |
| `locate` | Find files for a symbol or concept. |
| `blast_radius` | See direct and indirect dependents before editing a shared file. |
| `dependency_path` | Show an import chain between two files. |
| `core_files`, `chokepoints`, `subsystems` | Orient in an unfamiliar repository. |
| `import_cycles`, `refactor_order` | Inspect circular imports and plan a dependency-aware refactor. |
| `estelle_improve` | Request ranked security, structure, and quality proposals. |
| `estelle_read` | Read a file with freshness and coverage information. |
| `estelle_grep` | Search indexed text and see what could not be searched. |
| `estelle_explore` | List an indexed directory. |
| `estelle_context` | Retrieve cited source evidence within token and byte budgets, with a continuation when needed. |
| `estelle_write` | Update Estelle after you change a local file. It does not write your disk. |

On a multi-repository account, provide `repo: "owner/name"` when the tool accepts it. A refusal may ask for the repository rather than guessing one.

### Resume, remember, and hand off

| Tool | Use it to |
|---|---|
| `estelle_resume` | Resume the latest or a named session, optionally focused by task and repository. |
| `estelle_checkpoint` | Save a transcript-bearing session before stopping or exhausting context. |
| `estelle_activity` | Record client activity on a host without a transcript hook. |
| `list_sessions`, `list_threads` | Find past sessions individually or grouped by subject. |
| `get_session` | Read one session's stored, acknowledged diary entries. |
| `memory_chat` | Ask what was decided and receive a cited answer from stored memory. |
| `edit_memory`, `reinterpret_session` | Correct a memory or a session's meaning while retaining provenance. |
| `estelle_handoff`, `estelle_handoff_resume` | Move a task between sessions or hosts and see which recorded files changed. |
| `estelle_govern` | Compress a message history and report what was omitted. |
| `estelle_room`, `session_message` | Coordinate work and messages between live sessions. |
| `estelle_plan` | Maintain a task checklist through draft, approval, running, and completion. |
| `estelle_request` | Create or inspect a tracked request and its answer. |
| `estelle_docs` | Answer a question about Estelle itself from these published docs. On every account, with no setup and no usage charge. |
| `estelle_ask_parent` | Let a parallel child job ask its parent for a decision. |

### Read Atlas, publish pages, and inspect usage

| Tool | Use it to |
|---|---|
| `kb_ask` | Find Atlas pages related to a topic. |
| `kb_page` | Read a complete Atlas page or list available pages. |
| `estelle_plate`, `estelle_plate_read` | Publish a versioned brief, review, or measurement and read it later. |
| `estelle_usage` | Inspect credit spending and remaining balance. |
| `estelle_export` | Export everything Estelle holds for the account as downloadable files, including training files. See [Export your data](https://docs.fatelabs.ca/data-export). |
| `skill_find` | Find a relevant Estelle playbook for a task. |

### Investigate production and dependencies

| Tool | Use it to |
|---|---|
| `monitor_overview` | Read production error rates, issue counts, alerts, and uptime together. |
| `monitor_issues`, `monitor_issue` | List production issues and open one with recent occurrences. |
| `monitor_logs` | Search production logs. |
| `monitor_alerts`, `monitor_uptime` | Inspect alert rules and uptime checks. |
| `research_ask` | Ask a cited question about a dependency API or the codebase. |
| `research_watch`, `research_watchlist` | Enroll or change dependency watches and inspect the saved list. |
| `research_drift` | Check dependency changes against relevant call sites. |

Monitoring tools are read-only. `research_watch` changes the saved watchlist and takes a cadence of `off`, `hourly`, `daily`, or `weekly`.

### Review changes

| Tool | Use it to |
|---|---|
| `review` | Review a unified diff and return findings with file and line references. |
| `scan` | Scan a diff for security-sensitive findings. |
| `ontology_change` | Preview an ontology change and its consequences. A signed-in person applies it in the dashboard. |

### Start work

These tools can spend Estelle Credits. Confirm the repository, task, and any spend or iteration limits before starting them.

| Tool | Use it to |
|---|---|
| `work` | Request a checked code proposal for one task and existing file, or continue a returned job id. |
| `orchestra` | Run independent tasks in parallel, or preflight a dependency description without running it. |
| `orbit` | Arm, inspect, or stop bounded passes on one file. |
| `estelle_launch_agent` | Start a cloud coding agent in a Silo for a repository and task. |
| `estelle_return_agent` | Bring a cloud agent's work back to the calling host and report whether the return was verified. |
| `estelle_qa` | Plan or run Twice browser tests against a running web app. Preview the plan first. |

## Handle a tool refusal

A tool that cannot answer returns an error result rather than an empty success. Its machine-readable shape is:

```json
{
  "isError": true,
  "content": [{ "type": "text", "text": "..." }],
  "structuredContent": {
    "answered": false,
    "reason": "index_stale",
    "retryable": false,
    "message": "..."
  }
}
```

When a retry delay is known, `structuredContent.retry_after_s` is present and `retryable` is `true`.

Common reasons include:

| Reason | What to do |
|---|---|
| `missing_arguments`, `invalid_arguments` | Correct the named argument using the tool's advertised schema. |
| `repo_required`, `unknown_repo` | Supply an indexed `owner/name` available to this account. |
| `not_indexed` | Sweep the repository before asking navigation questions. |
| `index_stale`, `index_currency_unknown` | Reindex the current code, then retry. |
| `not_entitled` | Check account access and credits. Nothing was started. |
| `rate_limited`, `at_capacity`, `unavailable` | Retry after `retry_after_s` when provided, using backoff. |
| `no_grounded_answer`, `cannot_answer` | Change the question or inspect the available sources; this is not proof of absence. |

A refusal such as “not swept” or “could not verify” is not evidence that code is clean or a symbol is absent. Partial results are answers with limited coverage, not exhaustive findings.

If the server is at capacity before a tool runs, it can return JSON-RPC error `-32007`. Its `error.data` includes `retryable: true`, `retry_after_s`, and a `reason`. Retry after that interval; no tool action was performed.

## Related

- [Install Estelle](https://docs.fatelabs.ca/install): Complete the first connection and repository sweep.
- [CLI](https://docs.fatelabs.ca/cli): Generate client configuration and install session hooks.
- [Troubleshooting](https://docs.fatelabs.ca/troubleshooting): Resolve connection and authentication problems.