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

Threat	Likelihood	Impact	Mitigation
API key leak from client config	Medium	High	Dedicated keys; detect and warn on plaintext keys in known config paths; rotate exposed keys
Prompt-injection makes agent call destructive tool	High	High	Manifest sideEffects + annotations.destructive — host filters or asks user
Rate-limit abuse drives up cost	Medium	High	Infrastructure rate limits; dedicated keys; COLABHIVE_DENY_TOOLS client-side
Trained model from account A exposed to account B	Low	Critical	Visibility rules inherited from Actions API; hosted mode: SHA-256-keyed per-tenant pool; auth-scoped manifest endpoint
Cross-tenant data leak on hosted endpoint	Low	Critical	Each tenant has an isolated ColabHiveMCPServer and ManifestCache. Map key is SHA-256(api_key)[:16]; raw key never logged.
MITM between MCP server and ColabHive	Low	High	TLS-only to api.colabhive.com
MCP server crashes mid-call → client locks up	Medium	Medium	Structured exit codes + client retries; logs to stderr; systemd restart on host
Replay attack on mutating tool	Low	High	Idempotency keys where documented; host confirmation for tools marked sideEffects: ["mutating"]
Stale manifest serves removed tool	Low	Low	ETag 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.

Best practices for API keys (both modes)

1. Use one key per agent or machine. Granular scopes are not part of the public contract; 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

Item	Stored?	Retention
API keys (raw or hashed)	No	n/a — only kept in-process memory while the tenant is in the LRU pool
Prompts / tool inputs	No	n/a
Tool outputs	No	n/a
Tool calls (logs)	Structured logs only (see Logging)	Per your log retention
Tenant manifest cache	Yes — in memory only	Until 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 then accepts connections on every interface.

Browser access (CORS)

Not in the published package yet

COLABHIVE_CORS_ORIGINS ships in colabhive-mcp 0.4.0, which is not published on PyPI yet. The published release, colabhive-mcp==0.3.4, does not include it.

Until then --cors does not exist and COLABHIVE_CORS_ORIGINS has no effect.

The HTTP server sends no CORS headers unless COLABHIVE_CORS_ORIGINS / --cors lists exact origins; then a request from any other Origin gets 403. There is no wildcard. See Configuration.

Session lifecycle

Not in the published package yet

session_lifecycle ships in colabhive-mcp 0.4.0, which is not published on PyPI yet. The published release, colabhive-mcp==0.3.4, does not include it.

Until then a stdio session also answers tools/list and tools/call before initialize.

A stdio session answers only initialize and ping until the client has initialized, as the MCP lifecycle requires; tools/list and tools/call before that get JSON-RPC -32600. The HTTP transports are stateless: each request is its own session.

---

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.

Bucket	Default
API and invocation limits	Published by plan at colabhive.com/pricing; enforced at the infrastructure layer
Manifest fetches	Subject to infrastructure limits; no separate public tier is guaranteed
Cost ceilings	Deployment-specific; not a general public-plan promise

colabhive-mcp has no client-side call cap of its own. To bound what an agent can do, use a dedicated key and the local allow/deny lists described above.

---

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. The public MCP contract does not expose Prometheus metrics for tool-call counts, latency or errors.

---

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. Data handling remains deployment-specific; the platform does not currently enforce per-workload residency or provider restrictions.

---

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
• Run the local server as a non-root user with no shell

---

See also

• Configuration
• Manifests — side-effect declarations
• Architecture — hosted topology + per-tenant pool