How do I let my own Claude Code session investigate 5xx errors on an API with a project key?

Tares lets your own Claude Code session investigate 5xx errors on an API by connecting it with a project key that reads one project and records findings in it. You create the key under Settings, Keys, copy the secret once, and connect with claude mcp add and an Authorization Bearer header. Claude Code then reads the project’s sources, skills and earlier findings, and the finding it records shows on the project’s Overview under the key’s name.

How it works

A project key ties your Claude Code session to one Tares project. The key reads that project only and records findings in it. Any other call answers 403. Because the project is implied, the tools need no project argument.

Once connected, Claude Code works through the project tools:

• list_skills, then get_skill, to load a skill whose description matches the task.
• stats to see which values moved, and read for the entity’s timeline across the project’s sources. For 5xx errors, the entity is the API, for example api-server.
• list_findings and project_timeline to see what the Tares agents already concluded, so your session builds on it instead of repeating it.
• record_finding(entity, finding, verdict) when it concludes. The finding is markdown and the verdict is one lowercase word such as rca.

The project needs sources that carry the API’s data, such as logs or metrics, and a trigger. The AI SRE demo is a ready example. The full walkthrough for connecting an outside agent is in Connect an outside agent to a project.

Set it up

You need a running Tares instance with a project that has sources and a trigger, and the MCP endpoint running. The instance must be started with auth, or with TARES_AUTH_TOKEN set, so keys are checked. On an open instance there are no keys, so skip the key step and name the project in your prompts instead.

1. Start the MCP endpoint. It serves http://127.0.0.1:8788/mcp.

   tares mcp

2. Open the project, go to Settings → Keys, and choose New key.

3. Name the key after the agent that will hold it, such as claude-code. Every finding it records carries this name.

4. Copy the secret now. It is shown once.

5. Connect Claude Code with the key:

   claude mcp add --transport http tares http://localhost:8788/mcp \
     --header "Authorization: Bearer <project key>"

   Over stdio, start tares-mcp with TARES_AUTH_TOKEN=<project key> in its environment instead.

6. Check the connection in a Claude Code session:

   Use tares: which project can you work in?

   It calls list_projects and names the one project the key belongs to.

7. Ask about the errors. For example:

   Use tares: what 5xx errors did api-server show in the last 30 minutes? Check the project’s skills first, and record what you conclude.

8. Open the project to see the result. The finding is a card under What the agents found on the Overview, under the key’s name. In Advanced setup’s Activity it is a thread of its own, marked as recorded from outside Tares. It is also on the entity’s timeline in Explore.

What you get

• Claude Code investigates the 5xx errors inside the project, with the project’s sources, skills and earlier findings in reach.
• Your session sees what the Tares agents already concluded about the API and builds on it.
• The conclusion you record sits on the same timelines as the Tares agents’ findings. The next Tares agent that reads api-server starts from it.
• The key limits the session to one project. Any other call answers 403.
• You can cut the session off at any time by revoking the key under Settings → Keys.

Claude Code runs when you ask it. If you want an agent that runs on its own, such as a service with a webhook, it can join the project with join_project(url). Every firing of every trigger in the project, including triggers added later, is then sent to that URL. The agent shows under Agents on the project’s page, marked external. Revoking the key also removes its subscriptions. Revoke on the outside agent under Agents stops only the deliveries.

When something else fits

• Use another MCP client such as Codex, Cursor or your own agent if you do not work in Claude Code. The steps are the same and only the connect command differs, as described in Connect an outside agent to a project.
• Let the Tares agents investigate on their own if you want the 5xx investigation to start when a trigger fires, without you asking.

Related