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:

Vector Store A running vector database (e.g., Chroma) for storing embeddings. See Vector Storage for setup details.

Embedding Provider An embedding service (e.g., Ollama) to generate query vectors. See embedding model setup.

Storage Backend SQLite database for session storage and ancestry lookups. See Storage for configuration.

Start the API server with these flags:

tapes serve \
  --sqlite "./tapes.sqlite" \
  --vector-store-provider chroma \
  --vector-store-target "http://localhost:8000" \
  --embedding-provider ollama \
  --embedding-target "http://localhost:11434" \
  --embedding-model nomic-embed-text

For complete setup instructions including starting Chroma and installing embedding models, 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

depth Position in conversation tree

lineage Full conversation history leading to this turn

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...",
              "depth": 2,
              "lineage": [
                {
                  "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 vector storage and embedding configuration. If these are not configured, the server runs in "noop" mode with no tools available.

Required Flags

--vector-store-provider Vector store type (e.g., chroma)

--vector-store-target Vector store URL (e.g., http://localhost:8000)

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

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

--embedding-model Embedding model name (e.g., nomic-embed-text)

--sqlite SQLite database path

Noop Mode

If the vector store or 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.