> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiveninelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP — add the agent to your agent

> A hosted MCP server at api.fiveninelabs.com/mcp — the same sessions, as tools. Same keys, same budgets, same priced proposals.

<Warning>
  **Not yet available — planned.** The MCP server at `api.fiveninelabs.com/mcp` is not
  served today (the endpoint answers `501 not_implemented`) — the setup snippets below will not connect
  yet. This page is the contract the server ships against; the
  [changelog](/changelog) announces when it goes live. Until then, integrate via the
  REST API ([quickstart](/quickstart)).
</Warning>

The MCP server exposes Five Nine sessions to agent frameworks over streamable HTTP,
authorized by the same `fn_live_` / `fn_test_` bearer keys as the REST API. Long runs
follow a start-then-poll shape — `search` returns immediately, `get_session` is cheap
to poll — and tools return **bounded, structured summaries** with ids and URLs to go
deeper, never megabytes of rows.

```
Endpoint:  https://api.fiveninelabs.com/mcp
Transport: streamable HTTP
Auth:      Authorization: Bearer fn_live_… (or fn_test_…)
```

## Setup

**Claude Code:**

```bash theme={null}
claude mcp add fivenine --transport http https://api.fiveninelabs.com/mcp \
  --header "Authorization: Bearer $FIVENINE_API_KEY"
```

**Cursor / any MCP-JSON client:**

```json theme={null}
{
  "mcpServers": {
    "fivenine": {
      "url": "https://api.fiveninelabs.com/mcp",
      "headers": { "Authorization": "Bearer fn_live_..." }
    }
  }
}
```

Use the `fn_test_` key in CI — [test mode](/guides/test-mode) behaves identically
(replay-backed), so agent integration is testable at \$0.

## The tools

### `search` — ask a question, get a session id at once

Input: `{ query, max_spend_usd }` (both required — the budget ceiling applies exactly
as on REST). Returns
`{ session_id, status: "running", estimated_wait: "minutes — poll get_session" }`
immediately. A decline-to-spend returns `{ status: "abstained", reason, parsed }` —
\$0, stated, never a protocol error.

### `get_session` — poll for progress and the answer

Input: `{ session_id }` (also accepts an extraction id — one lookup tool serves both
run types). Once answered, returns a bounded digest: `qualified`, `records`,
`sources` with per-source receipt status, `spend_usd`, the top qualified rows (≤ 25,
with source attribution), `unchecked` (stated), and `result_url` for the full catalog.
Never the whole corpus.

### `follow_up` — narrows, asks, and priced re-aims

Input: `{ session_id, text, confirm?, max_spend_usd? }`. Narrows and asks return the
answer with row citations, free. A re-aim returns
`{ status: "proposal", proposal: { estimated_usd, passes, expires_at } }` — your agent
decides (or carries the quote back to its human), then calls again with
`confirm: true`. Pre-authorize with `max_spend_usd` to skip the round-trip. This is
the same [proposal flow](/guides/proposals) as REST, surfaced as structured results
on purpose: a calling agent can relay the price before money moves.

### `extract` — the URL-first path

Input: `{ url, entity, guidance?, max_spend_usd }`. One known catalog link, straight
to the extraction agent — no fan-out. Returns `{ extraction_id, status }`; poll with
`get_session`.

### `refresh` — fresh data at marginal cost

Input: `{ id, max_spend_usd, max_age_s? }` where `id` is `sess_…` or `ext_…`. Returns
the new run id, `served_from: "record"` when recency made it free, and the diff when
it re-ran.

### `list_sessions` · `whoami`

`list_sessions { limit?, status? }` → recent runs, one line each.
`whoami {}` → `{ account, key_name, balance_usd, open_reserves_usd, caps }` — lets an
agent check affordability **before** proposing spend to its human.

## Error behavior

REST error envelopes map into tool results with `code` preserved — a 402 comes back
as `{ status: "insufficient_credit", balance_usd, top_up_url }`, never as a protocol
error, so the calling agent can relay it and recover.

## Deliberate absences

Monitors are not in the v1 toolset: standing spend should be created by a human in
the dashboard or by code via REST — not by an agent mid-conversation.

## For agents reading these docs

Every page on this site has a `.md` variant at the same URL plus `.md`, and the site
serves [`/llms.txt`](https://docs.fiveninelabs.com/llms.txt) — start there.