Skip to main content

Claude Desktop

Connect Claude Desktop to ColabHive via MCP. Once configured, every ColabHive model — LLMs, specialists, tools, your trained models — appears as a tool Claude can call.

There are two paths: hosted (zero install) and local stdio. Pick one.

Path A — Hosted endpoint (recommended)​

Prerequisites​

  • Claude Desktop 0.7.0+ (Mac / Windows / Linux)
  • A ColabHive API key from console.colabhive.com → Settings → API Keys

That's it. No uv, no Python, nothing installed.

Config​

OSPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "colabhive": {
      "transport": "sse",
      "url": "https://mcp.colabhive.com/mcp",
      "headers": {
        "Authorization": "Bearer hive_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Some Claude Desktop builds want the key field as X-API-Key instead of Authorization. Both are accepted:

"headers": { "X-API-Key": "hive_xxx" }

Restart Claude Desktop fully (Cmd-Q / Alt-F4 + relaunch).

Verify​

In a new chat the 🔧 tools indicator should show "ColabHive: N tools". Ask:

What ColabHive tools can you use?

Then:

Use the ColabHive qwen-2.5-7b-instruct-public model to summarize this paragraph in Spanish: [paste text]

If you don't see tools, open Settings → Developer → MCP Logs → colabhive.

Path B — Local stdio (privacy / air-gapped)​

For setups where you don't want your API key to leave the machine.

Prerequisites​

  • Claude Desktop 0.7.0+
  • uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux)
  • A ColabHive API key

Config​

{
  "mcpServers": {
    "colabhive": {
      "command": "uvx",
      "args": ["colabhive-mcp@latest"],
      "env": {
        "COLABHIVE_API_KEY": "hive_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop.

The local server picks up COLABHIVE_API_KEY from the env block; the key never leaves your machine (apart from being sent to api.colabhive.com for inference calls, of course).

Recipes​

Use only your trained models​

{
  "mcpServers": {
    "colabhive": {
      "transport": "sse",
      "url": "https://mcp.colabhive.com/mcp",
      "headers": { "X-API-Key": "hive_xxx" }
    }
  }
}

ColabHive doesn't filter server-side by request; instead, mark your base models or other tools as not visible to your account in console.colabhive.com and they won't appear in tools/list. For finer control use the local stdio path with COLABHIVE_ALLOW_KINDS=trained_model.

Multi-environment (prod + staging)​

Two named servers, each with its own key:

{
  "mcpServers": {
    "colabhive-prod": {
      "transport": "sse",
      "url": "https://mcp.colabhive.com/mcp",
      "headers": { "X-API-Key": "hive_<prod-key>" }
    },
    "colabhive-staging": {
      "transport": "sse",
      "url": "https://mcp.colabhive.com/mcp",
      "headers": { "X-API-Key": "hive_<staging-key>" }
    }
  }
}

Cap costs / hide expensive generative​

Path A (hosted) does not enforce per-tool key scopes today. Use a dedicated key for independent revocation, but do not treat its displayed scopes as a security boundary.

In Path B (local stdio), use config flags:

"args": [
  "colabhive-mcp@latest",
  "--allow-kinds", "llm,specialist,tool,trained_model",
  "--stability", "stable"
]

Troubleshooting​

Path A: "MCP server failed to start" with hosted URL​

  • Verify network: curl https://mcp.colabhive.com/health should print JSON.
  • Verify the key works: the curl command from the installation page.
  • Make sure the JSON config has no trailing comma.

Path A: "Unauthorized" / no tools​

The key in your config is wrong, expired, or revoked. Check console.colabhive.com → API Keys.

Path B: "Command not found: uvx"​

uvx isn't in Claude Desktop's PATH. On macOS, launch Claude from Terminal so it inherits your shell PATH:

open -a "Claude"

Or use the full path:

"command": "/Users/yourname/.local/bin/uvx"

Logs clutter the chat window​

"env": {
  "COLABHIVE_API_KEY": "hive_xxx",
  "COLABHIVE_LOG_LEVEL": "error"
}

Security note​

In Path A, the key sits plaintext inside claude_desktop_config.json. Treat that file like a credential. Same in Path B under env.

When F2 OAuth lands you'll be able to do colabhive-mcp login in Path B and remove the key from the config entirely; tokens live in the OS keychain.

For Path A in the meantime, mitigate by:

  1. Scoping the key narrowly in console.colabhive.com
  2. Rotating it on a calendar reminder

See also​