MCP Integration

Connect Hindsight to any MCP-compatible AI client — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, or your own.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI applications connect to external tools over HTTP. Hindsight exposes its memory operations as MCP tools, so any MCP-compatible client can retain, recall, and reflect using your memory banks.

Prerequisites

• A Hindsight Cloud account with an API key (see Getting Started)
• An MCP-compatible client

Quick Setup

1. Go to the Connect tab in Hindsight Cloud
2. Copy the generated configuration for your MCP client
3. Paste it into your client's config file
4. Restart your client

The Connect page generates the configuration with your endpoint and selected bank pre-filled. You'll need to create an API key on the Connect page if you haven't already.

Connection Modes

Hindsight supports two MCP connection modes. The Connect page generates single-bank configs by default.

Single-Bank Mode (Recommended)

Your agent connects to one specific memory bank via the URL path:

https://api.hindsight.vectorize.io/mcp/{bank_id}/

• The agent is scoped to that bank — all operations (retain, recall, reflect) use it automatically
• No need for X-Bank-Id headers
• 27 tools available (memory operations, mental models, directives, documents, operations, tags, bank management + search_docs)
• Best for: dedicated agents, project-specific memory, team isolation

Multi-Bank Mode

Your agent connects to the root MCP endpoint and specifies the bank via a header:

https://api.hindsight.vectorize.io/mcp

With header: X-Bank-Id: {bank_id}

• Exposes 30 tools (adds list_banks, create_bank, and get_bank_stats)
• Each bank-scoped tool includes an optional bank_id parameter, so the agent can operate across multiple banks in a single session
• The X-Bank-Id header sets the default bank — if a tool call omits bank_id, this default is used
• If the X-Bank-Id header is omitted, the default bank is "default"
• Best for: cross-bank workflows, agents that need to manage or query multiple banks

Default bank behavior

In multi-bank mode, if you don't set the X-Bank-Id header, all operations default to a bank called "default". This bank is created automatically on first use. If you later switch to a different bank, any memories stored in the default bank stay there — they won't appear when querying the new bank.

To avoid confusion, always set X-Bank-Id to a meaningful name, or use single-bank mode where the bank is explicit in the URL.

Client Configurations

These examples use single-bank mode. Replace YOUR_BANK with your memory bank name and YOUR_API_KEY with the key from your Connect page.

Claude Code

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/ \
  --header "Authorization: Bearer YOUR_API_KEY"

Or add to .mcp.json (project-level) or ~/.claude.json (user-level):

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

Requires Node.js (for npx).

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
        "--header",
        "Authorization:${HINDSIGHT_API_KEY}"
      ],
      "env": {
        "HINDSIGHT_API_KEY": "Bearer YOUR_API_KEY"
      }
    }
  }
}

note

Claude Desktop doesn't support HTTP MCP servers directly in claude_desktop_config.json. npx automatically downloads and runs mcp-remote, which bridges the connection by wrapping the HTTP transport in stdio. The env block keeps the auth token out of the args to avoid a known Windows issue where spaces in args are mangled by cmd.exe.

Restart Claude Desktop to pick up the changes.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "hindsight": {
      "serverUrl": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

note

Windsurf uses serverUrl instead of url.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

note

VS Code uses servers instead of mcpServers.

Multi-Bank Configuration

To use multi-bank mode instead, point to /mcp and add the X-Bank-Id header:

Claude Code

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Bank-Id: YOUR_BANK"

JSON Config

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Bank-Id": "YOUR_BANK"
      }
    }
  }
}

Available Tools

Single-Bank Mode (27 tools)

Core Memory

Tool	Description
retain	Store information to long-term memory (supports tags, metadata, document association)
recall	Search memories with natural language (configurable budget, type/tag filters, time-scoped)
reflect	Get AI-powered answers using your memories as context (supports structured output)

Mental Models

Tool	Description
create_mental_model	Create a living document that stays current with your memories
list_mental_models	List all mental models in a bank
get_mental_model	Retrieve a specific mental model
update_mental_model	Update a mental model's name, query, or settings
delete_mental_model	Delete a mental model permanently
refresh_mental_model	Re-generate a mental model from latest memories

Directives

Tool	Description
list_directives	List directives that guide memory processing
create_directive	Create a new directive
delete_directive	Delete a directive

Memory Browsing

Tool	Description
list_memories	Browse memories with filtering and pagination
get_memory	Get a specific memory by ID
delete_memory	Delete a specific memory

Documents

Tool	Description
list_documents	List ingested documents
get_document	Get a specific document
delete_document	Delete a document and its linked memories

Operations

Tool	Description
list_operations	List async operations with status filtering
get_operation	Check operation status and progress
cancel_operation	Cancel a pending or running operation

Tags & Bank Management

Tool	Description
list_tags	List unique tags used in a bank
get_bank	Get bank profile (name, mission, disposition)
update_bank	Update bank name or mission
delete_bank	Delete an entire bank and all its data
clear_memories	Clear memories without deleting the bank

Cloud

Tool	Description
search_docs	Search Hindsight documentation

Multi-Bank Mode (30 tools)

All single-bank tools above, plus:

Tool	Description
list_banks	List all memory banks in your organization
create_bank	Create a new memory bank
get_bank_stats	Get bank statistics (node/link counts)

In multi-bank mode, every bank-scoped tool also accepts an optional bank_id parameter to target a specific bank.

Verifying the Connection

Ask your AI agent:

"What memory tools do you have available?"

It should list the Hindsight tools above. If no tools appear, check that:

1. Your API key is valid and active
2. The config file syntax is correct for your client
3. You restarted the client after adding the configuration

Memory Banks

Memory banks are isolated stores — each one is a separate memory space. Use different banks for different contexts:

• my-project for a specific project's context
• team-knowledge for shared team information
• One bank per agent for agent isolation

Banks are created automatically on first use (when you retain to a new bank name). You don't need to create them in advance.

To switch banks in single-bank mode, update the URL in your MCP config (e.g., change /mcp/project-a/ to /mcp/project-b/) and restart your client.

Usage and Billing

MCP operations consume credits just like SDK or API calls:

Operation	What's Billed
retain	Input tokens (content stored)
recall	Query + output tokens
reflect	Query + context + output tokens
get_mental_model	Output tokens (lightweight)
refresh_mental_model	Query + context + output tokens

Check your usage on the Usage Analytics page.

Troubleshooting

"Failed to connect" or no tools discovered

• Verify your API key hasn't been revoked (check the Connect page)
• Check that Authorization header uses Bearer prefix (with space)
• The bank name in the URL should only contain alphanumeric characters, hyphens, and underscores

Tools appear but operations fail

• Confirm your organization has available credits (see Billing)
• Check that your bank name is valid (alphanumeric and hyphens)

Memories not appearing after retain

Memory processing is asynchronous. After calling retain, fact extraction and indexing happen in the background. Wait a few seconds before recalling.

"0 tools discovered" after connecting

This usually means authentication failed silently. Double-check your API key is correct and the Authorization header is included.