Skip to main content

MCP Setup Guide

Get your AI tools connected to Headvroom in minutes.

Step 1: Generate an API Key​

Getting Your API Key​

  1. Go to headvroom.com and sign in
  2. Click your avatar in the top-right corner (or click your account node in Matrix view)
  3. In the Settings panel, find the API Keys section
  4. Click + Generate New Key
  5. Give your key a name (e.g., "Claude Desktop" or "Cursor")
  6. Copy the key immediately — it won't be shown again!
Keep Your Key Secret

Your API key grants full read access to all your graphs. If you think it's been compromised, delete it from Settings and create a new one.

Tips for Managing Keys​

  • Create one key per tool — If you stop using a tool, you can revoke just that key
  • Use descriptive names — "Claude Desktop MacBook" is better than "Key 1"
  • Check last used — Settings shows when each key was last used

Step 2: Configure Your AI Tool​

Claude Desktop Setup​

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "headvroom": {
      "command": "npx",
      "args": ["-y", "@headvroom/mcp"],
      "env": {
        "HEADVROOM_API_KEY": "your-api-key-here"
      }
    }
  }
}
Multiple MCP Servers

If you already have other MCP servers configured, add headvroom as another entry inside mcpServers:

{
  "mcpServers": {
    "existing-server": { ... },
    "headvroom": {
      "command": "npx",
      "args": ["-y", "@headvroom/mcp"],
      "env": {
        "HEADVROOM_API_KEY": "your-api-key-here"
      }
    }
  }
}

After saving:

  1. Fully quit Claude Desktop (Cmd+Q on Mac, not just close window)
  2. Reopen Claude Desktop
  3. Try: "What graphs do I have in Headvroom?"

Step 3: Verify Connection​

Testing Your Connection​

After restarting your AI tool, try these prompts:

  1. Basic test: "What graphs do I have in Headvroom?"

    • You should see a list of your graph names

  2. Load context: "Load my [Graph Name] from Headvroom and summarize it"

    • Replace [Graph Name] with one of your actual graphs

  3. Search: "Search my Headvroom graphs for [topic]"

    • Replace [topic] with something in your graphs

If these work, you're all set!

Not Working?​

See the Troubleshooting Guide for common issues and solutions.