> ## Documentation Index > Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Use the MCP server > Give a chat client or coding agent read access to your sessions, costs, outcomes and work items. The gateway serves an MCP endpoint at `/v1/mcp`. Its tools read your factory's sessions, costs, pull request outcomes, work items, runners and findings. One tool, `stop_build`, asks a runner to stop a build. The others change nothing. ## Tools | Tool | What it returns | Permission | | - | - | - | | `list_sessions` | A filtered, paged list of sessions. Covers the highest-spend repository unless you pass `repo` or `repoScope: "all"`. | `sessions.read` | | `get_session` | One session's transcript, by trace id. Capped at 2,000 spans; `truncated: true` marks a cut. | `sessions.read` | | `get_model_costs` | Each model's spend, requests and latency. Counts `unpricedSessions` separately from cost. Default: the last 7 days. | `metrics.read` | | `get_fleet_overview` | Fleet tiles such as sessions, tool-error rate and spend, against the period before. Default: the last 30 days. | `metrics.read` | | `list_context_changes` | Commits that changed `.outerlayer/` in your control plane, newest first. | `context.read` | | `compare_windows` | Fleet tiles for two date ranges you name, such as either side of a context change. | `metrics.read` | | `get_breakdown` | Spend or errors ranked by branch, agent type, worker kind, model or tool. Never by person. | `metrics.read` | | `get_trends` | Daily sessions, spend, tool-error rate and clean-session rate. A day with no sessions has no point. | `metrics.read` | | `get_pr_outcomes` | Which sessions produced pull requests, which needed a person, and what each pull request cost. Covers the highest-spend repository, with no date range. | `metrics.read` | | `list_work_items` | Live work items, filtered by repository, stage, section, claim, startable or `needs: "amend"`. | `work.read` | | `get_work_item` | One work item by number: stage, gate ledger, pull requests, sessions (each with the `claimId` of the attempt it ran in), build requests, claims (each with its `id`) and the acceptance criteria recorded for it. `criteria` is `null` when none are recorded, and `drafted` tells you the build wrote them from the issue description. | `work.read` | | `get_runner_log` | The runner's own log for one attempt on a work item, by item number and optionally an attempt's id from `claims`. It holds what the runner did around the agent, with secrets removed on the host. `log` is `null` while the attempt runs. | `work.read` | | `get_work_item_threads` | One work item's general thread and its criterion threads, each with who it is `waitingOn`, its latest verdict and its comments. | `work.read` | | `list_hosts` | Every runner that has checked in: its status, the `state` it last reported (`taking-work`, `draining`, `restarting`, `holding-for-update`, `blocked` or `low-disk`), the items it waits on while it drains, and the queues and repositories it takes. | `hosts.read` | | `stop_build` | Asks the runner building a work item to stop, by item number and an optional `note`, as `outerlayer work stop` does. Refused with `no_build_running` when no runner is building the item. | `work.update` | | `list_problems` | The factory's problems ranked by the work items they hit or by time lost, with each problem's strict keys. `since` and `until` window the figures; `command` and `file` narrow to one check. | `evidence.read` | | `get_problem` | One problem by id from `list_problems`: its figures and its findings, newest first, with cause, suggestion, error line, how each joined (`joinedBy`) and the other problems it reports. | `evidence.read` | | `get_findings_summary` | Findings and time lost per category, each finding counted once even when it reports several problems. | `evidence.read` | | `get_work_item_findings` | One work item's findings by item number, newest first, each with the problems it reports. | `evidence.read` | | `list_artifacts` | One work item's artifacts, by item number: file name, kind, caption, the criterion `--for` bound it to, pull request number and dashboard link. Leaves out an artifact a later one replaced. | `work.read` or `evidence.read` | The default Agent key lacks `metrics.read`, so the cost and trend tools refuse it with `403`. Use a key with the **Reader** preset, or add `metrics.read` to yours. See [API keys](/api-keys#choose-a-preset). Without `sessions.read_team`, `list_sessions` hides who ran each session and refuses a filter by person. Dates are UTC calendar dates. The server's one resource, a data model guide, explains the fields. A session with no stored price adds nothing to `cost` or `totalCost`. It is counted in `unpricedSessions` instead, so a total with a nonzero count is a lower bound. ## Install into a repository `outerlayer init` adds the entry for you. Its entry runs `npx -y @outerlayer/cli mcp serve`, so it works for everyone who clones the repository, with no global install. See [where `init` puts it](/reference/cli-capture). To add it yourself, run: ```bash theme={"system"} outerlayer mcp install ``` This writes an `outerlayer` entry into `.mcp.json` in the current directory, or into `.outerlayer/mcp.json` when that file exists. The entry runs `outerlayer mcp serve`, which reads your saved credential on each connect: a factory key, or your login once a factory is chosen. The key is never written into the file. The entry needs `outerlayer` on your `PATH`, so install the CLI with `npm install -g @outerlayer/cli`. For a client that cannot spawn a process: ```bash theme={"system"} outerlayer mcp install --transport http ``` This writes a direct entry that references `${OUTERLAYER_API_KEY}`. The client resolves it from its own environment. For the server name, a CLI that is not on `PATH`, or a self-hosted gateway, see every [`mcp install` flag](/reference/cli-context#outerlayer-mcp-install). ## Chat clients claude.ai and ChatGPT custom connectors take a URL and sign in over OAuth. Use the factory's own MCP address, with the **Factory Id** from **Settings → General**: ```text theme={"system"} https://api.outerlayer.ai/v1/apps//mcp ``` Add the connector in the client and sign in to the dashboard when prompted. The connector acts with your own permissions. To see the connectors you approved, or to revoke one, open **Profile → Connections → Connected apps** in the dashboard and choose **Disconnect**. The connector can no longer get new access. Also remove it in the client. A token the connector already holds keeps working for up to an hour after you revoke it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.