Use the MCP server

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.

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 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.

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:

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:

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.

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:

https://api.outerlayer.ai/v1/apps/<factory-id>/mcp

In the client, add a custom connector and paste the address.
Sign in to OuterLayer when the client opens it.
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:

Open Profile → Connections in the dashboard.
Under Connected apps, choose Disconnect for the connector.
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.

Next steps

API keys says how to create a key with the permissions the tools need.
Agent instructions covers the outerlayer-docs server.

Get started

Set up your factory

Keys and integrations

Work on an item

Automate

Configure a repository

Run builds

Prepare the build environment

Security and privacy

Troubleshoot and upgrade