Configuration
colabhive-mcp is configured via environment variables, CLI flags, or a config file. Precedence: CLI flag > env var > config file > default.
Required
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| API key | COLABHIVE_API_KEY | --api-key | — | Required unless you've run colabhive-mcp login (F2) |
Common
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| API base URL | COLABHIVE_API_URL | --api-url | https://api.colabhive.com | Use staging: https://api.staging.colabhive.com |
| Account ID | COLABHIVE_ACCOUNT_ID | --account-id | auto-detect from key | Override only if your key has multiple account contexts |
| Log level | COLABHIVE_LOG_LEVEL | --log-level | info | debug / info / warning / error |
| Log format | COLABHIVE_LOG_FORMAT | --log-format | json | json (structured) or text (human) |
| Request timeout | COLABHIVE_HTTP_TIMEOUT | — | 60 (s) | Per-HTTP call to ColabHive API (env or config file) |
| Sync timeout | COLABHIVE_SYNC_TIMEOUT | --sync-timeout | 30 (s) | Max wait for sync invocation before falling back to poll |
| Poll interval | COLABHIVE_POLL_INTERVAL | --poll-interval | 2 (s) | Between async polls |
| Poll max wait | COLABHIVE_POLL_MAX_WAIT | --poll-max-wait | 300 (s) | Total time before timing out a cold-path call |
Tool filtering
Limit which tools the agent sees — useful for cost control and reducing context bloat.
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| Allow list | COLABHIVE_ALLOW_TOOLS | --allow-tools | (all visible) | Comma-separated slugs or globs: qwen-*,web-* |
| Deny list | COLABHIVE_DENY_TOOLS | --deny-tools | (none) | Applied after allow list |
| Allowed kinds | COLABHIVE_ALLOW_KINDS | --allow-kinds | all | Comma list: llm,specialist,tool,trained_model,generative,model,operation |
| Deny side-effects | COLABHIVE_DENY_SIDE_EFFECTS | --deny-side-effects | (none) | Hide any tool whose manifest sideEffects include a listed value (e.g. network) |
| Stability floor | COLABHIVE_STABILITY | --stability | beta | experimental ≥ all; beta ≥ beta+stable; stable ≥ stable only |
Example — only let the agent use LLMs and your own trained models, never tools that hit the network:
export COLABHIVE_ALLOW_KINDS="llm,trained_model"
Example — only stable models, exclude expensive generative:
export COLABHIVE_STABILITY=stable
export COLABHIVE_ALLOW_KINDS="llm,specialist,tool" # excludes generative
Transport
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| Transport | — | sub-command | stdio | stdio (default if no sub-command), serve (HTTP/SSE), sdk-stdio / sdk-serve (official MCP SDK: strict stdio / stateless Streamable HTTP) |
| HTTP host | — | --host | 127.0.0.1 | Bind address for serve / sdk-serve |
| HTTP port | — | --port | 8765 | Listen port for serve / sdk-serve |
| SSE path | — | --sse-path | /mcp | URL path of the MCP endpoint |
Browser origins (CORS)
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.
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| CORS origins | COLABHIVE_CORS_ORIGINS | --cors | (none) | Comma list of exact browser origins allowed to call serve / sdk-serve, e.g. https://app.example.com |
Unset, the HTTP server adds no CORS headers, so a web page on another origin cannot read its
responses. Set, each listed origin gets CORS headers for the MCP endpoint, and a request whose
Origin header is not in the list is refused with 403 before it is authenticated. Requests
without an Origin header (desktop and CLI clients) are unaffected. * is refused at startup, as is
anything that is not scheme://host[:port]. The server never allows credentials: the API key
travels in a header, not a cookie.
If a reverse proxy in front of the server already adds CORS headers, configure origins in one place
only: two Access-Control-Allow-Origin headers make browsers reject the response.
Caching
The server caches the manifest in memory to avoid hammering /mcp/manifest on every tools/list.
| Setting | Env var | CLI flag | Default | Notes |
|---|---|---|---|---|
| Manifest TTL | COLABHIVE_MANIFEST_TTL | --manifest-ttl | 300 (s) | Refreshes on tools/list if TTL expired |
| Honor ETag | COLABHIVE_USE_ETAG | --no-etag (turns it off) | true | If-None-Match to avoid re-downloading unchanged manifests |
Config file
Instead of env vars, you can put settings in ~/.config/colabhive-mcp/config.toml (Linux/macOS) or %APPDATA%\colabhive-mcp\config.toml (Windows):
# ~/.config/colabhive-mcp/config.toml
api_key = "hive_xxx"
api_url = "https://api.colabhive.com"
log_level = "info"
[filter]
allow_kinds = ["llm", "specialist", "trained_model"]
deny_tools = ["z-image-turbo"]
stability = "stable"
[transport]
sync_timeout = 45
poll_max_wait = 600
manifest_ttl = 600
Validate it:
colabhive-mcp config --check
Multiple profiles
If you use ColabHive across staging + prod or multiple accounts:
# Profile 'prod'
colabhive-mcp --profile prod serve
# Profile 'staging'
colabhive-mcp --profile staging serve
Profiles live in ~/.config/colabhive-mcp/profiles/{name}.toml with the same shape as the main config file.
Reading current config
colabhive-mcp config --show
Prints the resolved configuration (with the API key redacted), showing where each value came from (env / flag / file / default).