Skip to main content

Claude Code

Connect Claude Code (Anthropic's terminal coding agent) to ColabHive via MCP.

Two paths: hosted (recommended) or local stdio.

Path A — Hosted endpoint​

Prerequisites​

  • Claude Code installed (pnpm i -g @anthropic-ai/claude-code or your installer of choice)
  • A ColabHive API key

Config​

Create or edit ~/.claude/mcp.json (global) or <project>/.mcp.json (project-scoped):

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

The ${env:COLABHIVE_API_KEY} lets you keep the key out of the file. Source it from your shell:

# ~/.zshrc or ~/.bashrc
export COLABHIVE_API_KEY=hive_xxx

Via the CLI​

# Global
claude mcp add colabhive --transport sse \
  --url https://mcp.colabhive.com/mcp \
  --header "X-API-Key: $COLABHIVE_API_KEY"

# Verify
claude mcp list
# colabhive  ✓ connected  (63 tools)

Path B — Local stdio​

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

Verify​

claude mcp list
# colabhive  ✓ connected

Inside Claude Code, type /mcp to see all registered servers.

Then prompt:

Use the ColabHive embeddings-public tool to embed each line of README.md.

Run my trained fraud-detector-v3 model on the rows in data/transactions.csv.

Recipes​

Restrict to safe tools​

Path A does not support enforced per-tool restrictions today. API-key scopes are stored but not enforced. In Path B, apply the restriction locally:

{
  "mcpServers": {
    "colabhive": {
      "command": "uvx",
      "args": [
        "colabhive-mcp@latest",
        "--deny-side-effects", "network,mutating,destructive",
        "--stability", "stable"
      ],
      "env": { "COLABHIVE_API_KEY": "${env:COLABHIVE_API_KEY}" }
    }
  }
}

CI usage​

# .github/workflows/data-pipeline.yml
- name: Run Claude Code task
  env:
    COLABHIVE_API_KEY: ${{ secrets.COLABHIVE_API_KEY }}
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude --headless --prompt "Use ColabHive embeddings-public to embed each row in data.csv and save to embeds.parquet"

Path A (hosted) is simpler in CI: nothing to install.

Reproducible CI​

There is no manifest pin: both paths read the live manifest. With Path B, fix the tools a CI run can see with COLABHIVE_ALLOW_TOOLS (see Configuration).

Troubleshooting​

claude mcp list shows "✗ connection error" (Path A)​

curl https://mcp.colabhive.com/health
# Should print JSON. If not, network issue.

claude mcp logs colabhive | tail -50
# Look for 401 (key issue) or 5xx (server issue).

Same error (Path B)​

uvx colabhive-mcp@latest --log-level debug 2>&1 | head -30

Most common: missing COLABHIVE_API_KEY in the launching shell.

Tool name not callable​

  • Manifest stale → claude mcp restart colabhive.
  • Tool not visible to your account → check console.colabhive.com.

Concurrency / hangs​

colabhive-mcp has no concurrency cap. A call that waits on a cold model gives up after --poll-max-wait seconds (default 300); Path B can lower it to fail sooner:

"args": ["colabhive-mcp@latest", "--poll-max-wait=60"]

See also​