How do I ask the Codex CLI to investigate error spikes with Tares?

Tares lets the Codex CLI investigate error spikes once you register the Tares MCP endpoint with codex mcp add and ask what happened to a service. Codex calls the read tool and answers from one correlated timeline of logs, metrics, alerts and findings. A question such as “what happened to api-server in the last 15 minutes?” is enough to start.

How it works

This is the pull side: you ask, and the agent reads on demand.

• Tares serves an MCP endpoint. On your machine it is http://localhost:8788/mcp. On your own server it is your domain followed by /mcp. On Tares Cloud it is shown under Connect in your console.
• Codex connects to that endpoint and discovers the Tares tools.
• When you name a service, Codex calls read with the label service set to that service. read returns a time-ordered timeline across every source that carries the label, so an error log burst, the metric that moved and the alert that fired appear on one clock.
• If a Tares agent or an outside agent already recorded a finding on that service, the read includes it. Codex starts from the earlier conclusion instead of from scratch.

The timeline joins on labels, so keep your metrics, logs and alert sources keyed by the same service label. The AI SRE guide shows that wiring end to end.

Set it up

1. Install Tares and start it. Then start the MCP server in a second shell, because the daemon alone does not serve /mcp locally.

uv tool install tares
tares up
tares mcp

2. Register the endpoint with Codex. Keep --url before the URL, because a bare URL registers a stdio server.

codex mcp add tares --url http://localhost:8788/mcp

3. If your instance is secured, which covers every server and Tares Cloud instance, give Codex a credential. Use an API key with the read scope and let Codex read it from an environment variable.

export TARES_API_KEY=<api-key>
codex mcp add tares --url https://<your-host>/mcp \
  --bearer-token-env-var TARES_API_KEY

4. Verify the connection. Ask Codex:

Use tares: what are you ingesting right now?

Codex should call catalog_list and answer with your sources, triggers and projects.

5. Ask about the spike. Name the service and the window:

Use tares: what happened to api-server in the last 15 minutes?

Codex calls read and answers from the correlated timeline. Swap in your own service name and a window that covers the spike.

6. Open the console and check Reads. Each read is listed as it happens and tagged client = mcp.

To see a spike without waiting for a real one, follow the demo in the AI SRE guide. It has an error_spike scenario that raises the api-server 5xx rate. The connecting agents page lists the setup for other clients, such as Claude Code and Cursor.

What you get

• One question gives you the logs, metrics, alerts and findings for a service in time order, not separate queries per system.
• Codex answers from evidence. It can tie the spike to specific log lines, the alert that fired and the metric that crossed a threshold.
• Follow-up questions use the same read. You can narrow to certain sources with sources, or look at the project with project_timeline.
• If a trigger already woke a Tares agent, its finding is part of the read. Each investigation leaves the timeline more useful for the next one.
• Codex can write back too. With a key that allows it, it can call record_finding to leave its conclusion on the entity, or remember to store an observation. Use create_trigger to be woken when the spike happens again.
• You can audit what Codex looked at in Reads in the console.

When something else fits

• If you want an investigation to start the moment a spike happens, without anyone asking, use a trigger that wakes an agent. That is the push side, covered in the AI SRE guide.
• If you would rather not wire up an external client, use Ask in the console. It is a chat loop inside Tares with the same read tools.
• If Codex should work inside one project only, use a project key instead of a broad read key. It reads that project and records findings in it, and nothing else.

Related