colabhive-mcp

Status: scaffold / not yet implemented. 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 (when published)

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

# Or pipx
pipx install colabhive-mcp

# Or pip
pip install colabhive-mcp

Quickstart (when published)

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.

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)