How do I let my own Claude Code session investigate slow database queries with a project key?

Tares lets your own Claude Code session investigate slow database queries once you create a project key and connect with claude mcp add and an Authorization Bearer header. The key reads that one project only and records findings there. You create it under Settings, Keys, New key, and the secret is shown once.

How it works

A project key ties your Claude Code session to a single Tares project. The session reads the project’s sources, loads its skills, sees what the Tares agents already concluded, and writes its own conclusions back onto the same timelines.

• Scope. The key reads this project only and records findings in it. Any other call answers 403.
• Identity. Every finding carries the name you gave the key, so a key named after the agent shows who wrote it.
• Implied project. With a project key the tools need no project argument.
• Transport. Claude Code connects over HTTP to the MCP endpoint that tares mcp serves at http://127.0.0.1:8788/mcp. Over stdio, you start tares-mcp with TARES_AUTH_TOKEN set to the project key instead.

For a slow-query investigation, the project should hold the data that shows the slowdown. That can be a Postgres source that reads a table on a cursor column, or Prometheus metrics you picked by name. The session then reads those timelines through the project tools.

The full walkthrough is in Connect an outside agent to a project. Keep the AI SRE demo in mind if you want a project to practice on.

Set it up

You need a running Tares instance with a project that has sources and a trigger. The instance must run with auth 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. The MCP endpoint must be running too.

1. Start the MCP endpoint in a terminal.

   tares mcp

2. Open the project that holds your database data, go to Settings, Keys, and choose New key.

3. Name the key after the agent, for example claude-code. Copy the secret straight away, because Tares shows it once.

4. Register Tares in Claude Code with the key in an Authorization Bearer header.

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

5. Check the connection from a Claude Code session with this prompt: Use tares: which project can you work in? Claude Code calls list_projects and names the one project your key belongs to.

6. Start the investigation with a prompt about the slowdown:

   Use tares: which queries on orders got slower in the last hour? Check the project’s skills first, and record what you conclude.

Claude Code then works through the project tools in this order:

1. list_skills, then get_skill for a skill whose description matches the task.
2. stats to see which values moved, and read for the entity’s timeline across the project’s sources.
3. list_findings and project_timeline to see what the Tares agents already concluded, so it builds on that.
4. record_finding(entity, finding, verdict) when it concludes. The entity is what the finding is about, the finding is markdown, and the verdict is one lowercase word such as rca.

What you get

• A Claude Code session that reads the same timelines your Tares agents read, so you do not paste query stats or metric values into the chat by hand.
• A finding on the project’s Overview, as a card under What the agents found, filed under the key’s name.
• A separate thread in the Activity view of Advanced setup, marked as recorded from outside Tares.
• The finding on the entity’s timeline in Explore, so the next Tares agent that reads that entity starts from your session’s conclusion.
• A key you control. To cut the session off, revoke the key under Settings, Keys.

If you want the session woken by the project’s triggers rather than by your prompt, an agent that runs on its own, such as a service with a webhook, can join the project with join_project(url). Claude Code runs when you ask it, so you do not need this for a hands-on investigation.

When something else fits

• If your instance is open and has no auth, there are no keys. Skip key creation and name the project in your prompts.
• If you use Codex, Cursor or your own agent, the same steps apply and only the connect command differs. See Connect an outside agent to a project and the connecting agents page it links to.
• If you want an agent that acts on every trigger firing with no prompt from you, have it join the project instead of waiting for you to ask.

Related