MCP Integration

Connect Hindsight to any MCP-compatible AI client — Claude Desktop, Claude Code, ChatGPT, 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 (see Getting Started)
• An MCP-compatible client

Authentication

Hindsight supports two authentication methods for MCP connections:

OAuth (Recommended)

Claude Code, Claude Desktop, ChatGPT, Cursor, and Windsurf support OAuth authentication. With OAuth:

1. Copy the config from the Connect page — no API key needed
2. When the client connects, it opens a browser for you to log in to Hindsight Cloud
3. The client receives a token automatically — no keys to manage or rotate

OAuth uses the MCP Authorization spec (RFC 9728) with PKCE for secure authentication.

API Key

For clients that don't support OAuth (VS Code), or as a fallback:

1. Create an API key on the Connect page
2. The key is embedded in your config as a Bearer token

You can switch between OAuth and API Key auth on the Connect page using the auth mode toggle.

Quick Setup

Claude Code (OAuth — Recommended)

The fastest way to get started:

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

Then in Claude Code, type /mcp to connect. A browser window opens for you to sign in to Hindsight Cloud. After signing in, your memory tools are ready to use. No API key needed.

Other Clients

1. Go to the Connect tab in Hindsight Cloud
2. Select your MCP client
3. Choose your auth mode (OAuth is recommended for supported clients)
4. Copy the generated configuration
5. Paste it into your client's config file
6. Restart your client — for OAuth clients, a browser login will open on first connection

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.

For OAuth clients, no API key is needed — the client handles authentication via browser login. For API key clients, replace YOUR_API_KEY with the key from your Connect page.

Claude Code

OAuth (Recommended)

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

Then type /mcp in Claude Code to connect. A browser window will open for you to sign in to Hindsight Cloud. After signing in, your memory tools are ready — no API key needed.

API Key (fallback)

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

OAuth (Recommended) — Connectors UI

1. Open Claude Desktop
2. Go to Settings → Connectors → Add custom connector
3. Enter this URL:

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

4. Click Connect — a browser will open for you to sign in to Hindsight Cloud

No API key, Node.js, or config file needed. Requires HTTPS.

note

Connectors is the officially supported way to connect Claude Desktop to remote MCP servers. Remote servers configured directly in claude_desktop_config.json will not connect natively.

Workaround: mcp-remote via JSON config

If Connectors doesn't work for your setup, you can use mcp-remote (a community tool) to bridge stdio to HTTP. Add this to ~/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/"
      ]
    }
  }
}

Requires Node.js. When Claude Desktop starts, mcp-remote will open a browser for you to log in. This is a community workaround, not officially documented by Anthropic.

API Key (fallback)

{
  "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"
      }
    }
  }
}

Requires Node.js. 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.

Cursor

OAuth (Recommended)

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

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

When Cursor connects, it will open a browser for you to log in.

API Key (fallback)

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

Windsurf

OAuth (Recommended)

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

{
  "mcpServers": {
    "hindsight": {
      "serverUrl": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/"
    }
  }
}

When Windsurf connects, it will open a browser for you to log in.

note

Windsurf uses serverUrl instead of url.

API Key (fallback)

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

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. VS Code does not currently support OAuth for MCP, so an API key is required.

ChatGPT

OAuth (Required)

1. Enable Developer Mode: Settings → Apps & Connectors → Advanced settings
2. Create a Connector: Settings → Connectors → Create
3. Enter a name (e.g. "Hindsight") and this URL:

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

4. Click Create — a browser will open for you to sign in to Hindsight Cloud
5. To use in a chat: click + in the message composer → More → select Hindsight

note

ChatGPT only supports OAuth for MCP connections — API key authentication is not supported. Requires HTTPS.

Multi-Bank Configuration

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

Claude Code (OAuth)

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp

The agent will use the "default" bank unless it specifies bank_id in tool calls.

API Key

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

Or in JSON:

{
  "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

OAuth login page doesn't open

• Make sure you're using a client that supports OAuth (Claude Code, Claude Desktop, ChatGPT, Cursor, Windsurf)
• Check that the MCP URL is correct and accessible
• For Claude Desktop, ensure Node.js is installed (npx must be available)

"Failed to connect" or no tools discovered

• OAuth: Try the connection again — the browser login may have timed out
• API Key: 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. For OAuth, try removing and re-adding the MCP server to trigger a fresh login.