colabhive-mcp

Status: 0.3.0 is running on the hosted production service at https://mcp.colabhive.com; the public PyPI index remains on 0.2.0 until the protected OIDC publishing environment is approved. See docs/plans/PLAN-mcp-layer-2026-05-22.md.

Model Context Protocol (MCP) server that exposes every ColabHive model — LLMs, specialists, tools, your trained models — to any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, n8n, …).

User-facing docs: https://docs.colabhive.com/mcp

Roadmap

Package layout (planned)

packages/mcp-server/
├── pyproject.toml
├── README.md                                  # this file
├── LICENSE                                    # MIT
├── src/
│   └── colabhive_mcp/
│       ├── __init__.py
│       ├── __main__.py                        # entry: `python -m colabhive_mcp`
│       ├── cli.py                             # argparse, sub-commands: serve, test, config, login, logout
│       ├── client.py                          # HTTP client for /api/builder/v1/{actions,mcp,invocations}
│       ├── manifest.py                        # ETag cache, refresh, schema validation
│       ├── auth.py                            # API key + OAuth device flow + keychain
│       ├── server_stdio.py                    # MCP stdio transport
│       ├── server_http.py                     # MCP HTTP/SSE transport (FastAPI)
│       ├── filters.py                         # allow/deny tools + kinds + stability
│       ├── invoke.py                          # sync/async glue, polling
│       ├── config.py                          # env + flag + TOML resolver
│       └── logging.py                         # structured JSON logger with redaction
├── tests/
│   ├── unit/
│   │   ├── test_manifest_cache.py
│   │   ├── test_filters.py
│   │   ├── test_invoke_sync_async.py
│   │   └── test_config_resolver.py
│   └── e2e/
│       └── test_full_flow.py                  # gated on COLABHIVE_API_KEY_STAGING
├── docs/
│   └── jsonrpc-examples/                      # captured frames for debugging
└── Dockerfile                                  # for HTTP/SSE deploy mode

Install from PyPI (after protected publication)

# Recommended (no global Python needed)
uvx colabhive-mcp@latest

# Or pipx
pipx install colabhive-mcp

# Or pip
pip install colabhive-mcp

Quickstart (after protected publication)

export COLABHIVE_API_KEY=hive_sk_xxx
colabhive-mcp test

Then add to your MCP client:

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

See user docs for full guides per client.

The 0.3.0 candidate also provides colabhive-mcp sdk-stdio and colabhive-mcp sdk-serve, strict stdio and stateless Streamable HTTP transports implemented with the official MCP Python SDK. Both reuse the same tenant-scoped core, discovery filters and call gates. The historical default stdio and hosted HTTP/SSE transports remain unchanged while clients migrate and parity is proven.

Experimental Cohort tools

Version 0.3.0 adds six opt-in tools without changing any existing tool: cohort_capabilities, plan_cohort, run_cohort, get_cohort, explain_cohort, and cancel_cohort. They are hidden and cannot be called by name unless all of the following are true:

• COLABHIVE_MCP_COHORT_TOOLS_ENABLED=true locally;
• MCP stability permits experimental tools;
• Builder reports Cohort capability for the authenticated account;
• normal allow/deny kind and side-effect filters permit the operation.

run_cohort returns promptly with a task ID and accepts an idempotency key. Status and explanation are redacted control-plane JSON; prompts, completions and tensors are never added to MCP responses. The hosted server is production-deployed; these tools remain hidden unless every local, stability and Builder capability gate passes.

Dev (when scaffolding lands)

# From repo root
uv pip install -e packages/mcp-server[dev]

# Run unit tests
pytest packages/mcp-server/tests/unit

# Run E2E against staging (needs API key)
COLABHIVE_API_KEY_STAGING=hive_sk_xxx \
COLABHIVE_API_URL=https://api.staging.colabhive.com \
  pytest packages/mcp-server/tests/e2e

# Run manually in stdio mode
COLABHIVE_API_KEY=hive_sk_xxx python -m colabhive_mcp

# Run in HTTP/SSE mode
COLABHIVE_API_KEY=hive_sk_xxx python -m colabhive_mcp serve --port 8765

Dependencies (planned)

Compliance with CLAUDE.md rules

• REGLA #0 — No engine names hardcoded. Tool kind is derived from the manifest, which comes from _compute_kind() in builder-gateway. This package never compares engine strings.
• REGLA #1 — DB is the only source of truth. Manifests are fetched, not invented. Missing manifest field → missing in MCP output, no defaults.
• REGLA #2 — mcp_stability reflects lifecycle_status. Filtering by --stability stable excludes candidate (= beta).
• REGLA #4 — Publish to PyPI with checksum + tag + latest version follows the same rigor as wheel deploys.
• REGLA #7 — E2E tests cover the production-critical models listed in the master plan.

License

MIT — see LICENSE.

Links

• 📖 Docs: https://docs.colabhive.com/mcp
• 🛠 Master plan: docs/plans/PLAN-mcp-layer-2026-05-22.md
• 🐛 Issues: https://github.com/colabhive/colabhive-api/issues (label mcp)
• 🔒 Security: security@colabhive.com (see top-level SECURITY.md)