Scout for Claude Code

Claude Code connects to Scout over MCP with one command in a terminal. From then on your agent can call the scout_* tools in every project: one call at the start of a session returns the team's live state, and it writes contracts, decisions, lessons and handoffs as it works. The same command covers the Code tab in the Claude desktop app.

What you get

Claude Code reaches Scout as an MCP server, through the scout_* tools.

At the start of a session your agent calls scout_session_bundle. It returns what changed since this seat last read, the team's rules, open contract changes, active handoffs, deprecated patterns to avoid, and what each teammate is working on right now. It is sized to a token budget you set.

The paste

Save your key once as SCOUT_API_KEY. Setup shows the command for that beside the key, at the moment the key is created.

Then run this in a terminal. Copy the MCP URL from Setup. Here, your-team stands in for your workspace's slug.

claude mcp add --transport http --scope user scout https://api.runscout.dev/mcp/your-team --header "Authorization: Bearer $SCOUT_API_KEY"

Run it in a terminal where SCOUT_API_KEY is set. --scope user adds Scout for every project and keeps the key in your user settings, not in the repository. Restart any open Claude Code session afterwards.

To check that Claude Code registered Scout: claude mcp list, or /mcp inside a session.

Or sign in

Add Scout with no key. Then sign in. Your browser opens to approve Scout.

claude mcp add --transport http --scope user scout https://api.runscout.dev/mcp/your-team

claude mcp login scout

Or run /mcp inside a Claude Code session and choose scout. claude mcp login needs Claude Code 2.1.186 or later. If you already added scout with a key, remove it first with claude mcp remove scout.

CLAUDE.md

Nothing to add to a rules file. Your agent reads the team's rules through the session bundle as soon as MCP is connected.

Change a rule in Scout once. Every teammate's agent picks it up at its next session.

Your first session

Setup confirms on the page when your agent connects. If it does not, restart Claude Code and paste the short check Setup gives you.

Your agent checks that the scout_* tools are there. If they are not, it tells you and stops.

When it connects, Scout tells it which repositories the workspace covers and how to work with the team's record.

If the workspace is new, Scout's first answer asks it to read only those repositories, write a handful of contracts, decisions and lessons, and show you what it wrote so you can correct it.

Troubleshooting

Your agent does not see the scout_ tools: Restart the session. A server added part-way through one is not loaded until the agent starts again, and reconnecting is not enough. If it works in one project but not another, the server was added for that project only — adding it with --scope user registers it everywhere.
Your agent says Scout refused it as unauthorized: Your tool is not sending a working key, or it is not signed in. The key-based steps on Setup read SCOUT_API_KEY, set to the secret of the named key you picked, so check that variable is set where the tool runs: open a new terminal after saving it, then restart the tool. Claude Desktop cannot read it from your shell at all — its config needs the key written in where it says <YOUR_API_KEY>, or add Scout as a custom connector and sign in through the browser instead. If you replaced a key, the variable may still hold the old secret. A new named key does not revoke the others.
Your agent connected, but it found nothing to read: This workspace is probably watching no repositories yet, so the record really is empty — there is nothing wrong with the connection. Connect one in Connections. That is an admin action, so if you are not an admin, ask one of them to do it and then run your agent again.