Connecting agents (MCP)

Connect Claude Code, Codex, Cursor, or any MCP client to Tares and ask questions like “what happened to api-server in the last 15 minutes?”. The client discovers the Tares tools and answers from the correlated timeline: logs, metrics, alerts, and findings in one read.

1. Get your endpoint

The MCP endpoint depends on where Tares runs:

Running locally? The daemon alone does not serve /mcp. Start the MCP server as a second process:

tares mcp --transport streamable-http --port 8788 --taresd http://localhost:8787

On a server or Tares Cloud instance the MCP server is already running; there is nothing to start.

2. Connect your client

The snippets below use the local endpoint, http://localhost:8788/mcp. Connecting to a server or Tares Cloud instance? Replace the URL with yours and add the credential from Authentication. The console’s Connect page generates these exact commands with the endpoint and token filled in.

/plugin marketplace add glassflow/tares
/plugin install tares@tares

claude mcp add --transport http tares http://localhost:8788/mcp

claude mcp add --transport http tares https://<your-host>/mcp \
  --header "Authorization: Bearer <api-key>"

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

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

{
  "mcpServers": {
    "tares": {
      "url": "http://localhost:8788/mcp"
    }
  }
}

{
  "mcpServers": {
    "tares": {
      "url": "http://localhost:8788/mcp"
    }
  }
}

{
  "mcpServers": {
    "tares": {
      "type": "http",
      "url": "http://localhost:8788/mcp",
      "headers": { "Authorization": "Bearer <api-key>" }
    }
  }
}

3. Verify

Ask your client:

Use tares: what are you ingesting right now?

The client should call catalog_list and answer with your sources, triggers, and projects. Running the demo? Ask “what happened to api-server in the last 15 minutes?” and it answers from the correlated timeline. In the console, Reads lists each read as it happens, tagged client = mcp.

Authentication

On a secured instance (tares up --auth, every server and Tares Cloud instance), the MCP surface requires a credential. Prefer a scoped API key with the read scope over the root token:

• HTTP: the client sends Authorization: Bearer <api-key>; the server forwards it to the daemon. Each client tab above shows where the header goes.
• stdio: set TARES_AUTH_TOKEN=<api-key> in tares-mcp’s environment.

For an agent that should work inside one project only, use a project key instead: it reads that project and records findings in it, and nothing else.

On an open instance (plain tares up), no credential is needed.

Transports

The Tares MCP server supports two transports:

• streamable-http: the MCP server runs as a network endpoint and the client connects over HTTP. This is the default path used above, and the only one for remote instances.
• stdio: the client spawns tares-mcp as a subprocess; it proxies to the daemon at TARESD_URL. Use it for an agent on the same machine as the daemon when you’d rather not run the HTTP server. tares-mcp is installed with the tares package.

The stdio shape for clients that take a config object:

{
  "mcpServers": {
    "tares": {
      "command": "tares-mcp",
      "env": {
        "TARESD_URL": "http://localhost:8787",
        "TARES_AUTH_TOKEN": "<api-key, only on a secured instance>"
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add tares \
  --env TARESD_URL=http://localhost:8787 \
  -- tares-mcp

Tools

The MCP server exposes the following tools. A key’s scope determines which succeed: a read key gets the read surface; writing (ingest, source management) needs the matching scope.

A typical agent flow: read any entity on the fly; or catalog_list / catalog_describe to learn what’s there, read with sources to look at just the ones that matter, create_trigger to be woken when it happens again, and remember to write back what it found.

create_trigger, update_trigger and create_source take an optional project (an id or a name); left out, the object goes to the Default project. See Projects.

The tools of kind project work inside one project. With a project key the project is implied; otherwise pass project (an id or a name), which may be left out while the instance has only one project. See Connect an outside agent to a project.

Set up sources with an agent

The setup tools make source configuration conversational: the agent does what you would do in the console form, against the same validation:

Use tares to ingest the orders table from my Postgres, keyed by tenant_id.

1. discover_source: introspects the upstream from partial config and returns a proposed source (for Postgres: reads information_schema to pick the cursor and key columns). discover_docker scans the local Docker environment and proposes one source per running container.
2. test_source: dry-runs the config: fetches sample events without creating anything, so the agent (and you) can check the labels and key before committing.
3. create_source: creates it; ingestion starts immediately, no restart.

Every connector page shows the agent prompt next to the console and YAML forms. Because all paths normalize to the same stored config, a source an agent creates exports to the same catalog YAML as one you click together.

In-app agent

The console includes Ask, the same idea hosted inside Tares: a chat loop on the daemon with the read tools, for exploring or debugging your data without wiring up an external client. Open it under Ask in the console, or summon it anywhere with ⌘K.