Skip to main content

Security

colabhive-mcp is the bridge between your AI agent and ColabHive's full model catalog. Treat its config like a credential file — because it is one.

Threat model​

ThreatLikelihoodImpactMitigation
API key leak from client configMediumHighF2 OAuth + keychain (planned); detect & warn on plaintext keys in known config paths
Prompt-injection makes agent call destructive toolHighHighManifest sideEffects + annotations.destructive — host filters or asks user
Rate-limit abuse drives up costMediumHighInfrastructure rate limits; dedicated keys; COLABHIVE_DENY_TOOLS client-side
Trained model from account A exposed to account BLowCriticalVisibility rules inherited from Actions API; hosted mode: SHA-256-keyed per-tenant pool; auth-scoped manifest endpoint
Cross-tenant data leak on hosted endpointLowCriticalEach tenant has an isolated ColabHiveMCPServer and ManifestCache. Map key is SHA-256(api_key)[:16]; raw key never logged.
MITM between MCP server and ColabHiveLowHighTLS-only to api.colabhive.com
MCP server crashes mid-call → client locks upMediumMediumStructured exit codes + client retries; logs to stderr; systemd restart on host
Replay attack on mutating toolLowHighF4 HMAC + nonce + timestamp on sideEffects: ["mutating"] tools (planned)
Stale manifest serves removed toolLowLowETag refresh on tools/list; deprecation warnings surfaced to agent

Auth​

Hosted mode — header passthrough (live)​

Every request to mcp.colabhive.com/mcp must carry an API key in one of:

Authorization: Bearer hive_xxx
# or
X-API-Key: hive_xxx

The server does not have a master key. The request's key is what's used downstream. If it's missing or invalid, the server returns 401. If it's valid but lacks visibility on a tool, that tool simply isn't in the response.

This is the same model as every other ColabHive API call. There's no separate "MCP key" — your existing hive_... works.

Local stdio mode (live)​

export COLABHIVE_API_KEY=hive_xxx
uvx colabhive-mcp@latest

Or via --api-key flag, or ~/.config/colabhive-mcp/config.toml.

The key never leaves your machine except to api.colabhive.com for inference calls.

OAuth 2.1 device flow (planned, F2)​

Will let you do:

colabhive-mcp login
# Open https://colabhive.com/auth/device, enter code ABCD-1234

Tokens stored in the OS keychain (macOS Keychain, libsecret on Linux, DPAPI on Windows). access_token 1h, refresh_token 30d, automatic renewal. Revocable per-client.

Best practices for API keys (both modes)​

  1. Use one key per agent or machine. Granular scopes are stored but are not enforced yet; a dedicated key still gives you independent rotation and revocation.
  2. Never commit keys. Add *.mcp.json and colabhive-mcp/config.toml to .gitignore.
  3. Rotate quarterly. Set a calendar reminder.
  4. One key, one machine. If a laptop is lost, revoke that key.

What the hosted server stores​

ItemStored?Retention
API keys (raw or hashed)Non/a — only kept in-process memory while the tenant is in the LRU pool
Prompts / tool inputsNon/a
Tool outputsNon/a
Tool calls (logs)Structured logs only (see Logging)Per your log retention
Tenant manifest cacheYes — in memory onlyUntil LRU eviction (typically minutes)

Logs record, per tool call: timestamp, sha-prefix of the api_key, slug, status, and latency. They do not record arguments or outputs.

Network surface​

Hosted endpoint​

mcp.colabhive.com:443 (TLS via Let's Encrypt, Cloudflare in front).

Open routes:

  • GET /health — no auth required, returns liveness JSON
  • POST /mcp — JSON-RPC, requires API key
  • GET /mcp — SSE keep-alive channel, requires API key
  • POST /admin/manifest/refresh — force-refresh tenant's cache, requires API key

Local stdio mode​

The default. The server does not open any inbound port — it communicates over stdin/stdout with the MCP client that launched it.

Local HTTP mode​

colabhive-mcp serve --host 127.0.0.1 --port 8765

Binds only to 127.0.0.1 by default. Override with --host 0.0.0.0 only if you understand the implications — the server prints a clear warning in that case.

Side-effects enforcement​

Tools declare side-effects in their manifest (see Manifests). The agent host can:

  1. Auto-deny classes of tools — e.g. reject all mutating in a "safe browse" session.
  2. Confirm with user before annotations.destructive: true or sideEffects: ["mutating"].
  3. Surface warnings when calling pii tools.

In local stdio mode, colabhive-mcp enforces an additional client-side allow/deny:

export COLABHIVE_DENY_TOOLS="web-*"
# or
colabhive-mcp --deny-side-effects=mutating,destructive

Hosted mode does not provide an equivalent per-tool deny today. API-key scopes are visible in the Console but are not enforced by the Builder API yet. Use a dedicated key for revocation and choose local stdio when a client-side tool allow/deny policy is required.

Rate limiting​

api.colabhive.com enforces per-account limits. Hosted MCP just propagates them; on 429, the server translates into an MCP error with the original Retry-After hint, and the agent should back off.

BucketDefault
API and invocation limitsEnforced at the infrastructure layer; public per-plan tiers are not yet published
Manifest fetchesSubject to infrastructure limits; no separate public tier is guaranteed
Cost ceilingsDeployment-specific; not a general public-plan promise

Client-side ratchet (local stdio only, today):

colabhive-mcp serve --max-calls-per-minute 20

Logging​

The MCP server emits structured logs only — there is no separate audit API and no audit database table. Each tool call produces one structured log line via the server's logger:

mcp.tool.invoked  slug=qwen-2.5-7b-instruct-public  status=succeeded  latency_ms=287

The record carries the timestamp, a SHA prefix of the API key (never the raw key), the tool slug, status, and latency — not the arguments or the model output. In local stdio mode these go to stderr (control with COLABHIVE_LOG_LEVEL / COLABHIVE_LOG_FORMAT); in hosted mode they are structured JSON logs (see Architecture → Observability).

For usage, billing, and per-account activity, use console.colabhive.com. Prometheus metrics for tool calls / latency / errors are on the roadmap (not emitted today).

Data residency​

For each tool call via MCP:

  1. Input travels: your machine → (hosted) → ColabHive API → node runtime → model container.
  2. Output flows back the same way.
  3. No payload is persisted in MCP-layer infrastructure.
  4. Trained model artifacts stay in your account's MinIO bucket (SSE-S3 encrypted at rest).

In hosted mode the only extra hop vs Actions API is mcp.colabhive.com itself, which is operated by ColabHive (same data residency policy as the rest of the platform).

Reporting a vulnerability​

Found a security issue? Do not file a GitHub issue. Email security@colabhive.com with:

  • Reproduction steps
  • Affected versions
  • Suggested severity (CVSS if you can estimate)

We respond within 24 h, fix-or-mitigate within 7 d for High/Critical.

Hardening checklist​

For production / enterprise deployments:

Hosted​

  • Use a dedicated API key for the MCP integration (not your main key); scopes are not an enforcement boundary yet
  • Agree deployment-specific usage and cost limits where required
  • Enable audit log retention ≥ 90 days
  • Rotate the key quarterly

Local stdio​

  • All of the above
  • Use OAuth (F2) once available
  • Set COLABHIVE_STABILITY=stable to exclude beta tools
  • Set COLABHIVE_DENY_TOOLS for tools with mutating / destructive side-effects you don't need
  • Pin a manifest snapshot via --manifest-pin <etag>
  • Run the local server as a non-root user with no shell
  • Pin certs with --cert-pin sha256:... if you operate inside a strict egress proxy

See also​