Connecting agents (MCP)

Tares exposes its read (and authoring) surface to agents over the Model Context Protocol(MCP). An MCP client connects, discovers the Tares tools, and calls them. The console’s Agents → Connect tab generates the exact commands below for your instance, with the endpoint and token filled in.

This page is about connecting an external agent that lives in your own infrastructure and can act on your systems. For an agent that runs inside Tares, waking on a trigger to write a finding, see Tares agents.

Transports

The Tares MCP server supports two transports.

stdio: the client spawns tares-mcp as a subprocess; it proxies to the daemon at TARESD_URL. Use for an agent on the same machine as the daemon, or where the client manages a local process.
streamable-http: the MCP server runs as a network endpoint and the client connects over HTTP. Use for a remote/deployed instance.

tares-mcp (stdio) is an entry point installed with the package. The HTTP server is started with tares mcp:


tares mcp --transport streamable-http --host 0.0.0.0 --port 8788 --taresd http://localhost:8787
# serves http://<host>:8788/mcp

A bare tares up does not serve /mcp; that is the daemon only. In the Docker deployment, the compose file runs the MCP server as a separate service and routes /mcp to it, so the endpoint is https://<host>/mcp.

Authentication

On a secured instance (tares up --auth), the MCP surface requires a credential. Prefer a scoped API key - read for a read-only agent, over the root token:

HTTP: the client sends Authorization: Bearer <api-key>; the server forwards it to the daemon.
stdio: set TARES_AUTH_TOKEN=<api-key> in tares-mcp’s environment.

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

Clients

Claude Code (plugin)

The Tares plugin is the default path for Claude Code. One install wires both directions: the MCP read-back and session capture into the claude_code source.


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

The install prompts for the Tares URL, an optional auth token (stored in the OS keychain), and a capture toggle. It requires the tares package on PATH (for tares-mcp). To connect without capturing sessions, use the CLI tab instead.

Claude Code (CLI)

HTTP (remote/deployed instance):


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

stdio (same machine as the daemon):


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

Generic (HTTP)

For Claude Desktop, Cursor, and other clients that take an MCP config object:


{
  "mcpServers": {
    "tares": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Generic (stdio)

stdio requires the tares package installed where the agent runs:


{
  "mcpServers": {
    "tares": {
      "command": "tares-mcp",
      "env": {
        "TARESD_URL": "http://localhost:8787",
        "TARES_AUTH_TOKEN": "<token>"
      }
    }
  }
}

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.

tool	kind	description
`read`	read	a correlated, time-ordered timeline across all sources matching a `{label: value}` selector (strict AND), no view needed
`query`	read	a correlated, time-ordered timeline for an entity through a view; select by `key` or `where`
`catalog_list`	read	list sources, views, and triggers
`catalog_describe`	read	one object’s schema, entities, freshness, lineage, and sample events
`list_sources`	read	sources with their config and live health
`list_connectors`	read	connector types and their fields
`derive`	write	create a view correlating sources for a `key_field`
`remember`	write	write an observation to the agent-memory source
`subscribe`	write	register a webhook to be pushed when a trigger fires
`discover_source`	setup	introspect an upstream and return a proposed source config
`discover_docker`	setup	scan the local Docker environment for sources
`test_source`	setup	dry-run a source config without creating it
`create_source`	setup	create a source (ingestion starts immediately)

A typical agent flow: read any entity on the fly; or catalog_list / catalog_describe to learn what’s there, derive to save a view, query to read it, and remember to write back what it found.

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.

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.
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.
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 an Ask view, the same idea, hosted inside Tares. It runs a chat loop on the daemon with the read tools plus derive, using an Anthropic API key you provide in the browser (sent per request, not stored). Use it to explore or debug a source’s data without wiring up an external client. Open it under Ask in the console, or summon it anywhere with ⌘K.