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

# Use the MCP server

> Connect a coding agent or chat client to read your factory's sessions, costs, outcomes and work items, and to stop a build.

The OuterLayer MCP server lets a coding agent or chat client read your factory's data. It reads sessions, costs, pull request outcomes, work items, runners and findings. One tool, `stop_build`, asks a runner to stop a build. The other tools change nothing.

`outerlayer init` adds two MCP servers to a repository. This page covers `outerlayer`, which reads your factory's data. The other, `outerlayer-docs`, searches these docs. See [Agent instructions](https://docs.outerlayer.ai/agent-context.md).

## Before you start

The tools you can call depend on how the server signs in:

* **Your login, or a chat connector.** The server acts as you, so each tool follows your role. The Read role can call every tool except `stop_build`, which needs the Admin or Owner role.
* **A factory key.** Each tool needs the permission in the [Tools](#tools) table. A key with the Agent preset can call only the tools that need `sessions.read`, `work.read` or `context.read`. For the other tools, use the **Reader** preset or add the permission. See [Choose a preset](https://docs.outerlayer.ai/api-keys.md#choose-a-preset).

## Connect a coding agent

In a repository set up with `outerlayer init`, the server is in place. Sign in on your machine with `outerlayer login`.

To add the server to another directory, run:

```bash theme={"system"}
outerlayer mcp install
```

The command writes an `outerlayer` entry to `.mcp.json` in the current directory. If `.outerlayer/mcp.json` exists, it writes there.

The entry runs `outerlayer mcp serve`, so `outerlayer` must be on your `PATH`. Install the CLI with `npm install -g @outerlayer/cli`.

The server reads your saved credential each time it connects: a factory key, or your login after you choose a factory. The file never holds the key.

For a client that cannot start a process, run:

```bash theme={"system"}
outerlayer mcp install --transport http
```

This entry connects to `https://api.outerlayer.ai/v1/mcp` on OuterLayer Cloud. It sends `Authorization: Bearer ${OUTERLAYER_API_KEY}`, so set `OUTERLAYER_API_KEY` in the client's environment.

For the other flags, see [`outerlayer mcp install`](https://docs.outerlayer.ai/reference/cli-context#outerlayer-mcp-install).

## Connect claude.ai or ChatGPT

A custom connector in claude.ai or ChatGPT takes a URL and signs in with OAuth. Use the factory's own MCP address, with the **Factory ID** from the factory's **Settings → General**:

```text theme={"system"}
https://api.outerlayer.ai/v1/apps/<factory-id>/mcp
```

1. In the client, add a custom connector and paste the address.
2. Sign in to OuterLayer when the client opens it.
3. On **Connect to OuterLayer**, check the client's name and choose **Allow access**.

The connector acts as you. It can call every tool that your role allows, and that includes `stop_build`.

## Tools

| Tool | What it does | Permission |
| - | - | - |
| `list_sessions` | Lists sessions, with filters. | `sessions.read` |
| `get_session` | Returns one session's transcript, up to 2,000 spans. | `sessions.read` |
| `get_model_costs` | Returns each model's spend, requests and latency. Default: the last 7 days. | `metrics.read` |
| `get_fleet_overview` | Returns totals such as sessions, tool-error rate and spend, with the period before. Default: the last 30 days. | `metrics.read` |
| `compare_windows` | Compares the same totals for two date ranges that you name. | `metrics.read` |
| `get_breakdown` | Ranks spend or errors by branch, agent type, worker kind, model or tool. Never by person. | `metrics.read` |
| `get_trends` | Returns daily sessions, spend, tool-error rate and clean-session rate. | `metrics.read` |
| `get_pr_outcomes` | Shows which sessions produced pull requests, which needed a person, and what each pull request cost. | `metrics.read` |
| `list_context_changes` | Lists the commits that changed `.outerlayer/` in your control plane, newest first. | `context.read` |
| `list_work_items` | Lists work items, with filters such as repository, status and claim. | `work.read` |
| `get_work_item` | Returns one work item: its status, pull requests, sessions, build requests, claims, acceptance criteria and checks. | `work.read` |
| `get_work_item_threads` | Returns one work item's comment threads, with who each thread waits on. | `work.read` |
| `get_work_item_attachment` | Returns one attachment of a comment. | `evidence.read` |
| `list_artifacts` | Lists one work item's artifacts. | `work.read` or `evidence.read` |
| `get_runner_log` | Returns the runner's log for one attempt on a work item, with secrets removed. The log is empty while the attempt runs. | `work.read` |
| `list_hosts` | Lists each runner with its status, its state, and the queues and repositories it takes. | `hosts.read` |
| `stop_build` | Asks the runner that builds a work item to stop, as `outerlayer work stop` does. | `work.update` |
| `list_problems` | Lists the factory's problems, ranked by the work items they hit or by time lost. | `evidence.read` |
| `get_problem` | Returns one problem with its findings, newest first. | `evidence.read` |
| `get_findings_summary` | Returns findings and time lost for each category. | `evidence.read` |
| `get_work_item_findings` | Returns one work item's findings, newest first. | `evidence.read` |

Each tool describes its own parameters to the client. The server also has one resource, a guide to the data model.

These rules apply to the results:

* `list_sessions` and `get_pr_outcomes` cover the repository with the highest spend. For `list_sessions`, pass `repo` to name another repository, or `repoScope: "all"` for all of them.
* Dates are UTC calendar dates.
* A session with no stored price adds nothing to `cost` or `totalCost`. It counts in `unpricedSessions`. A total with a count above zero is a lower bound.
* A key without `sessions.read_team` cannot see who ran each session, and `list_sessions` refuses a filter by person. The Reader preset holds `sessions.read_team`.

## Disconnect or rotate

To revoke a connector:

1. Open **Profile → Connections** in the dashboard.
2. Under **Connected apps**, choose **Disconnect** for the connector.
3. Remove the connector in the client.

A token that the connector holds can work for up to an hour after you revoke it.

After you rotate a factory key, your editor's MCP server uses the new key the next time it connects. See [Rotate or revoke](https://docs.outerlayer.ai/api-keys.md#rotate-or-revoke).

## Next steps

* [API keys](https://docs.outerlayer.ai/api-keys.md) says how to create a key with the permissions the tools need.
* [Agent instructions](https://docs.outerlayer.ai/agent-context.md) covers the `outerlayer-docs` server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.