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

> Integrate MCP servers with Hindsight easily using this complete configuration guide. Expose memory tools via FastMCP instances without extra infrastructure.

- Repository: [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight)
- Tags: how-to-guide
- Published: 2026-03-13

---

**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`](https://github.com/vectorize-io/hindsight/blob/main/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`](https://github.com/vectorize-io/hindsight/blob/main/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`](https://github.com/vectorize-io/hindsight/blob/main/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`](https://github.com/vectorize-io/hindsight/blob/main/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:

```bash
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**:
   ```bash
   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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```python
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`](https://github.com/vectorize-io/hindsight/blob/main/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`](https://github.com/vectorize-io/hindsight/blob/main/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.