How to Set Up MCP Server Integration with Hindsight: Complete Configuration Guide

The Hindsight API includes a built-in Model Context Protocol server that exposes memory tools through FastMCP instances, supporting both single-bank isolation via URL paths and multi-bank management via HTTP headers without requiring additional infrastructure.

The vectorize-io/hindsight repository provides a self-contained memory layer for LLM applications with native MCP support built directly into the API server. When you start the Hindsight API, the MCPMiddleware class in hindsight_api/api/mcp.py automatically instantiates FastMCP servers that expose memory operations as MCP tools, making it straightforward to set up MCP server integration with Hindsight using only environment variables and standard HTTP clients.

Architecture of the Built-In MCP Server

The Hindsight MCP implementation consists of three core components that handle request routing, tool registration, and context management.

ASGI Middleware and Request Routing

The MCPMiddleware class (lines 12-150 in hindsight_api/api/mcp.py) intercepts all incoming ASGI requests. When a request path starts with /mcp, the middleware:

• Extracts and validates the Authorization header using either the legacy static token or the ApiKeyTenantExtension
• Resolves the target bank ID through URL path parameters, the X-Bank-Id header, or the HINDSIGHT_MCP_BANK_ID environment variable
• Injects context variables (_current_bank_id, _current_api_key, _current_tenant_id, _current_api_key_id) for downstream tool access
• Rewrites the request path to strip bank-specific segments before forwarding to the appropriate FastMCP application

Server Creation and Tool Registration

The create_mcp_server function (lines 7-71 in hindsight_api/api/mcp.py) builds a FastMCP instance and registers available tools via register_mcp_tools. The server configuration uses MCPToolsConfig (defined in hindsight_api/mcp_tools.py lines 30-70) to specify bank-ID resolvers, API-key validation, and the complete tool catalog.

MCP Server Modes and Endpoint Configuration

Hindsight exposes two distinct operational modes that determine which tools are available and how bank isolation is enforced.

Single-Bank Mode (Memory-Only Tools)

Accessed via http://<host>:<port>/mcp/<bank_id>/, this mode exposes only memory-focused tools including retain, recall, and reflect. The bank ID is extracted exclusively from the URL path (e.g., /mcp/alice/), and tool calls do not require a bank_id parameter in the request payload.

Multi-Bank Mode (Full Tool Suite)

Available at http://<host>:<port>/mcp or /mcp/, this endpoint exposes all 29 tools including bank-management operations like list_banks, create_bank, and delete_bank. Bank selection follows this priority order:

1. X-Bank-Id HTTP header
2. HINDSIGHT_MCP_BANK_ID environment variable (defaults to "default")
3. Explicit bank_id parameter in tool calls

Environment Variable Configuration

Configure the MCP server behavior using these environment variables:

Variable	Purpose	Default
HINDSIGHT_API_MCP_ENABLED	Master switch to enable/disable MCP endpoints	true
HINDSIGHT_MCP_BANK_ID	Fallback bank ID when not specified in URL or headers	"default"
HINDSIGHT_API_MCP_AUTH_TOKEN	Legacy static bearer token for simple authentication (optional)	unset
HINDSIGHT_API_LOG_LEVEL	Logging verbosity for MCP operations (debug, info, warning)	info

Define these in a .env file in your project root; the Hindsight CLI automatically loads them when starting the server.

Authentication Configuration

Open Access (Default)

By default, Hindsight uses DefaultTenantExtension, which permits all requests without authentication. This mode is suitable for local development or trusted networks.

API Key Authentication

For production deployments, enable strict authentication by setting:

HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
HINDSIGHT_API_TENANT_API_KEY=your-secure-secret-key

With this configuration, the MCPMiddleware requires every request to include an Authorization: Bearer your-secure-secret-key header. Requests without valid credentials receive a 401 response before reaching any tools.

Step-by-Step MCP Server Setup

Follow these steps to activate and configure the MCP server:

1. Enable the MCP server by ensuring HINDSIGHT_API_MCP_ENABLED=true in your environment (enabled by default).

2. Select your operational mode:

   • Use single-bank mode for dedicated memory access to one bank per endpoint
   • Use multi-bank mode when managing multiple memory banks through one endpoint

3. Configure authentication based on your security requirements—either leave open for development or set HINDSIGHT_API_TENANT_EXTENSION and HINDSIGHT_API_TENANT_API_KEY for production.

4. Start the API server:

   hindsight start

   The FastAPI application mounts the MCP endpoints at the configured paths (default /mcp).

5. Verify connectivity using a simple curl request to list available tools.

Connecting MCP Clients to Hindsight

Claude Code (Single-Bank Configuration)

Connect Claude Desktop to a specific memory bank where the URL path determines the target bank:

claude mcp add \
  --transport http \
  hindsight \
  http://localhost:8888/mcp/alice/ \
  --header "Authorization: Bearer super-secret-key"

After connection, Claude can invoke retain, recall, and reflect without specifying bank_id parameters.

Claude Code (Multi-Bank Configuration)

Connect to the root endpoint to access all bank management capabilities:

claude mcp add \
  --transport http \
  hindsight \
  http://localhost:8888/mcp \
  --header "X-Bank-Id: bob" \
  --header "Authorization: Bearer super-secret-key"

Each tool call must include "bank_id": "bob" in the parameters, or you must consistently provide the X-Bank-Id header.

Testing with curl

Verify the single-bank endpoint and list available tools:

curl -X POST http://localhost:8888/mcp/alice/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Create a new bank using the multi-bank endpoint:

curl -X POST http://localhost:8888/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer super-secret-key" \
  -d '{
    "jsonrpc":"2.0",
    "method":"create_bank",
    "params":{"bank_id":"new-bank","name":"Demo Bank"},
    "id":2
  }'

Python SDK Integration

Use the hindsight_client library to interact with the MCP server programmatically:

from hindsight_client import Hindsight

# Connect to single-bank endpoint

client = Hindsight(
    base_url="http://localhost:8888/mcp/alice/",
    api_key="super-secret-key"
)

# Store a memory

await client.retain(
    content="User prefers dark mode interfaces",
    context="ui_preferences",
    tags=["user:alice", "settings"]
)

# Retrieve memories

results = await client.recall(query="What UI preferences does Alice have?")

For multi-bank access, instantiate the client with the root endpoint (http://localhost:8888/mcp) and pass bank_id to each method call or configure the client to include the X-Bank-Id header by default.

Summary

• The MCP server is built into Hindsight via MCPMiddleware in hindsight_api/api/mcp.py and requires no separate installation.
• Two operational modes exist: single-bank (URL-path based, memory tools only) and multi-bank (header-based, all 29 tools including bank management).
• Configuration is environment-driven using variables like HINDSIGHT_API_MCP_ENABLED and HINDSIGHT_MCP_BANK_ID.
• Authentication integrates with the tenancy system—either open access or API-key validation through ApiKeyTenantExtension.
• Clients connect via standard HTTP MCP transport, including Claude Desktop, curl, or the Python SDK, using the appropriate headers for bank resolution.

Frequently Asked Questions

What is the difference between single-bank and multi-bank MCP modes?

Single-bank mode restricts the endpoint to one specific bank ID encoded in the URL path (e.g., /mcp/alice/), exposing only memory operations like retain and recall that automatically target that bank. Multi-bank mode operates at the root /mcp path, exposes all 29 tools including bank lifecycle management, and requires the bank_id to be specified via the X-Bank-Id header or environment variables for each request.

How do I secure the Hindsight MCP server with authentication?

Set HINDSIGHT_API_TENANT_EXTENSION to hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension and provide a secret via HINDSIGHT_API_TENANT_API_KEY. The MCPMiddleware will then validate the Authorization: Bearer <token> header on every MCP request, rejecting unauthorized access before reaching any tool implementations. Alternatively, set HINDSIGHT_API_MCP_AUTH_TOKEN for a simpler legacy token scheme.

Can I run the MCP server without the full Hindsight API?

No. The MCP server is implemented as ASGI middleware within the main FastAPI application in hindsight_api/api/mcp.py. It shares the same process and database connections as the REST API, ensuring consistent state across all interfaces. You cannot deploy the MCP server as a standalone service separate from the Hindsight API.

Which MCP tools are available in each mode?

Single-bank mode exposes memory-focused tools: retain, recall, reflect, forget, and similar operations that interact with memories within the URL-specified bank. Multi-bank mode includes these plus administrative tools like list_banks, create_bank, delete_bank, get_bank_stats, and export_bank, allowing clients to manage the entire bank lifecycle through the MCP protocol.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}