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 both the session DAG 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 stored LLM sessions. Returns the most relevant sessions based on query text, including full conversation lineage.

Input Parameters

query The search query text (required)

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

Output Format

Returns a JSON object containing:

query The original search query

count Number of results returned

results Array of search results

Each result includes:

hash Unique identifier for the conversation turn

score Similarity score (higher is more relevant)

role Message role (user, assistant, system)

preview Content snippet

turns Number of turns in the matched conversation chain

branch The conversation chain leading to this turn (each entry has hash, role, text, and matched)

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "query": "how to configure logging",
          "count": 3,
          "results": [
            {
              "hash": "abc123...",
              "score": 0.89,
              "role": "assistant",
              "preview": "To configure logging, you'll need to...",
              "turns": 2,
              "branch": [
                {
                  "hash": "xyz789...",
                  "role": "user",
                  "text": "How do I set up logging?"
                },
                {
                  "hash": "abc123...",
                  "role": "assistant",
                  "text": "To configure logging, you'll need to..."
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

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.