MCP API

The Model Context Protocol (MCP) server provides a standardized HTTP interface for AI agents to search stored tapes sessions.

Important: The MCP server is not a hosted service. It runs locally as part of your tapes API server. You must start tapes with vector storage and embedding configuration to enable the MCP endpoint.

Endpoint

When you run the tapes API server locally, the MCP endpoint is available at:

POST http://localhost:8081/v1/mcp

Port 8081 is the default API server port. Configure with --api-listen flag.

Prerequisites

The MCP endpoint requires the following to be configured:

PostgreSQL with pgvector Holds the captured sessions and embeddings. Use tapes local up to bootstrap. See PostgreSQL Storage.

Embedding Provider An embedding service (Ollama or OpenAI) to generate query vectors. See embedding model setup.

Start the API server with these flags:

tapes serve \
  --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable" \
  --embedding-provider ollama \
  --embedding-target "http://localhost:11434" \
  --embedding-model embeddinggemma

For complete setup instructions, see the Search guide.

Available Tools

search

Perform semantic search over the span projection. Hits are individual main-conversation LLM spans with their trace and turn context — the same shape the /v1/search/spans HTTP endpoint returns.

Input Parameters

query The search query text (required)

top_k Number of results to return (optional, default: 5)

Output Format

The tool result's content[0].text is a JSON string encoding an object with:

query The original search query

count Number of results returned

results Array of search results

Each result includes:

session_id The owning session

trace_id The trace (turn) the matched span belongs to

span_id The matched span

score Similarity score (higher is more relevant)

user_prompt The user prompt of the turn the span belongs to

snippet Matched content from the span

model The model that produced the span

started_at When the span started

Request/Response Examples

Example Request

MCP protocol request to search for sessions:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "how to configure logging",
      "top_k": 3
    }
  }
}

Example Response

The envelope carries the payload as a JSON string in content[0].text:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"query\":\"how to configure logging\",\"count\":1,\"results\":[...]}"
      }
    ]
  }
}

Decoding that string yields:

{
  "query": "how to configure logging",
  "count": 1,
  "results": [
    {
      "session_id": "0196fdb1-93f4-7c41-a53d-0fbe2c5e1f23",
      "trace_id": "trc_52d1d48c-9b88-486d-96ca-8c6eac122946",
      "span_id": "llm_776e5b37-66d5-48e9-b6fc-c9721c7b027d",
      "score": 0.89,
      "user_prompt": "How do I set up logging?",
      "snippet": "To configure logging, you'll need to...",
      "model": "claude-sonnet-4-5",
      "started_at": "2026-06-10T20:09:33Z"
    }
  ]
}

Configuration

Enabling MCP

The MCP endpoint is automatically enabled when you start the API server with both Postgres and embedding configuration. If these are not configured, the server runs in "noop" mode with no tools available.

Required Flags

--postgres PostgreSQL DSN (with pg_duckdb + pgvector extensions)

--vector-store-target Optional. pgvector DSN; defaults to --postgres when unset

--embedding-provider Embedding provider type (e.g., ollama)

--embedding-target Embedding provider URL (e.g., http://localhost:11434)

--embedding-model Embedding model name (default: embeddinggemma)

Noop Mode

If the embedding provider is not configured, the MCP server runs in "noop" mode with no tools registered. The endpoint remains available but returns an empty tools list.

Integration

The MCP endpoint implements the Model Context Protocol specification. For agent integration examples and higher-level usage, see the Agents guide.

For more information about the Model Context Protocol, visit the MCP specification.