MCP server configuration¶

mcp connects Colossus to explicitly configured Model Context Protocol servers. A server may be a local process using stdio or an exact remote endpoint using Streamable HTTP. Remote servers are stateful by default, with an explicit stateless compatibility opt-in.

Colossus exposes only the MCP tool surface:

Resources, prompts, sampling, and elicitation are not exposed. MCP configuration does not bypass access selection, policy authorization, approval obligations, sandbox grants, quarantine, redaction, or audit.

For a step-by-step connection workflow, see MCP.

Choose a starting point¶

Prefer explicit tool names for stable deployments. Use the wildcard only when the configured server itself is trusted to publish future callable tools.

Supported MCP surface¶

The native remote transport targets MCP 2025-11-25 and requires stateful Streamable HTTP by default. It supports bounded JSON and SSE responses, server session headers, POST requests, stateful GET event streams, and best-effort DELETE session cleanup. allowStateless: true permits one reviewed server to omit Mcp-Session-Id; it does not enable a different protocol version or legacy transport. For one-way JSON-RPC frames, the bounded HTTP adapter accepts an empty successful response as equivalent to 202 Accepted; requests still require a valid bounded JSON or SSE response.

The following modes are not enabled:

• The legacy HTTP+SSE transport with separate message and event endpoints.
• Streamable HTTP semantics specific to the 2026-07-28 release candidate.
• Automatic request retry or transparent expired-session reinitialization.

Each discovery page and tool call receives a fresh initialized transport. Colossus closes a negotiated session best-effort after the result. Explicitly stateless servers receive no GET event stream or DELETE cleanup because they publish no session identity. If a remote call may have reached the server but completion cannot be confirmed, the effect becomes OutcomeUnknown and is not automatically retried.

Top-level mcp fields¶

mcp:
  oauthCredentialStore: auto
  servers: {}

Server names use 1–128 ASCII letters, digits, dots, underscores, or hyphens. The OAuth store setting has no effect when no server configures OAuth.

Local stdio servers¶

Stdio is the default transport, so transport: stdio may be included for clarity or omitted for compatibility with existing configuration:

mcp:
  oauthCredentialStore: auto
  servers:
    local-docs:
      transport: stdio
      command: /absolute/path/to/venv/bin/docs-mcp-server
      args: [--stdio]
      workingDirectory: /absolute/path/to/repository
      environment:
        API_TOKEN: env:HOST_DOCS_API_TOKEN
      allowedTools: [search_docs, read_document]
      timeoutMs: 30000
      maxOutputBytes: 1048576

Under an isolating boundary, matching sandbox configuration must grant the executable, working directory, and child environment name:

sandbox:
  executables:
    - /absolute/path/to/venv/bin/docs-mcp-server
  filesystem:
    - root: /absolute/path/to/repository
      mode: read
  environment:
    - API_TOKEN

This sandbox block is an isolation-only fragment. Acknowledged full access supplies ambient resources, and adding the fragment does not narrow them. In the environment mapping, API_TOKEN is the name visible inside the child and HOST_DOCS_API_TOKEN is the host variable Colossus reads. The sandbox grant names the child variable, not the host variable. Using the same name for both is also valid.

Stdio fields¶

When workingDirectory is omitted, Colossus uses the selected workspace; under isolation it still needs a containing filesystem grant. Arguments do not use shell expansion, executable lookup, or command substitution. An isolating boundary supplies only declared environment names; acknowledged full access supplies ambient environment authority.

Stdio MCP is a process effect. The MCP child receives only permit-authorized process, filesystem, environment, network, time, output, process-count, and memory obligations. Colossus writes one initialized request batch and keeps stdin open only until the final operation response, an initialization error, malformed or truncated protocol output, child exit, or the effect timeout. It then closes stdin and supervises cleanup. Each discovery page and tool call still uses a fresh process. The server owns its own TLS implementation and does not inherit network.caBundlePath.

Remote Streamable HTTP servers¶

Remote MCP uses one exact endpoint and is a network effect:

mcp:
  oauthCredentialStore: auto
  servers:
    splunk:
      transport: streamable_http
      url: https://splunk.example.com/services/mcp
      credentialHeaders:
        Authorization:
          scheme: Bearer
          reference: env:SPLUNK_MCP_TOKEN
      allowStateless: true
      allowedTools:
        - splunk_run_search
        - splunk_get_indexes
      timeoutMs: 30000
      maxOutputBytes: 1048576
sandbox:
  environment:
    - SPLUNK_MCP_TOKEN
  networkDestinations:
    - https://splunk.example.com

Under isolation, merge the sandbox fields into the deployment's sandbox block. The credential reference is stored in YAML; its value is resolved only inside the permit-bearing MCP adapter. Under an isolating boundary, a remote credential header requires the referenced host variable itself in sandbox.environment and the endpoint requires the listed destination. Permit-bound discovery and calls under acknowledged full access supply both resource authorities; keeping these entries does not narrow that ambient boundary.

Remote transport fields¶

The URL must not contain a username, password, query, or fragment. Under an isolating boundary, HTTPS is required except for exact localhost or IP-loopback development endpoints. Acknowledged full access also accepts canonical non-loopback plaintext HTTP; it has no TLS confidentiality or server authentication and can expose MCP request content or credentials in transit. Every request remains bound to the exact configured endpoint; the transport cannot redirect itself to a different path or origin.

Under an isolating boundary, the endpoint origin must match sandbox.networkDestinations. Public * may match a public HTTPS origin, but loopback, private, link-local, and metadata destinations require an exact origin. Acknowledged full access supplies the endpoint resource without the duplicate grant; it does not discover a server or widen allowedTools. Remote MCP uses Colossus's pinned-DNS, redirect-free, ambient-proxy-free HTTP client and inherits additional roots from Network trust configuration.

Static headers and credentials¶

Use headers only for non-secret routing metadata:

headers:
  X-Tenant-ID: operations

Use credentialHeaders for authorization or API-key values:

credentialHeaders:
  Authorization:
    scheme: Bearer
    reference: env:SPLUNK_MCP_TOKEN
  X-Api-Key:
    reference: env:SPLUNK_SECONDARY_KEY

scheme is optional. When present, Colossus sends SCHEME secret; when omitted, it sends the secret value alone. A scheme contains only bounded ASCII letters, digits, hyphens, or underscores.

Header names are case-insensitively unique. Colossus rejects transport-managed headers, cookies, proxy credentials, Mcp-* names, and literal authorization-like headers. Header values must be nonempty, bounded, and free of control characters. A resolved credential that is empty or contains CR/LF is rejected.

Literal headers may accompany static credentials or OAuth. credentialHeaders and oauth are mutually exclusive because both own the authentication identity.

Static credential headers are the simplest choice for unattended operation when the server supports a long-lived or externally rotated token.

OAuth 2.1 with PKCE¶

OAuth is an alternative to credentialHeaders:

mcp:
  oauthCredentialStore: auto
  servers:
    splunk:
      transport: streamable_http
      url: https://splunk.example.com/services/mcp
      oauth:
        clientId: colossus
        clientSecretReference: env:SPLUNK_MCP_CLIENT_SECRET
        callbackPort: 8787
        scopes: [openid, offline_access]
      allowedTools: [splunk_run_search, splunk_get_indexes]
      timeoutMs: 30000
      maxOutputBytes: 1048576
sandbox:
  environment:
    - SPLUNK_MCP_CLIENT_SECRET
  networkDestinations:
    - https://splunk.example.com
    - https://identity.example.com

The identity origin is illustrative. Under isolation, authorize the actual protected-resource, authorization, and token origins discovered for the deployment; when sandbox.backend is danger_full_access, only globally configured sandbox.acknowledgeDangerFullAccess: true supplies ambient authority for the operator-run login ceremony. A session-only TUI acknowledgement applies to permit-bound MCP turns and does not authorize mcp auth login. Without the global acknowledgement, grant the client-secret environment name and every actual protected-resource, authorization, and token origin exactly. OAuth discovery and token exchange use the same declared-or-ambient network policy, TLS roots for HTTPS, DNS pinning, redirect rejection, timeout, and response bounds as other Colossus-owned clients.

OAuth fields¶

Colossus performs protected-resource and authorization-server discovery, PKCE-S256, CSRF state validation, issuer validation, token exchange, expiry handling, and refresh rotation. The configured client secret remains behind its environment reference and is not persisted with OAuth credentials.

Login, status, and logout¶

Normal interactive login binds the callback only on 127.0.0.1, prints the authorization URL, and waits up to five minutes for the bounded callback request:

colossus --config .colossus/config.yaml mcp auth login splunk

For a headless host or container, copy the authorization URL to a browser, complete the flow, and paste the final redirected URL into stdin:

colossus --config .colossus/config.yaml mcp auth login splunk --manual

Inspect local token presence or remove the local record:

colossus --config .colossus/config.yaml mcp auth status splunk
colossus --config .colossus/config.yaml mcp auth logout splunk

status reports whether a local token record exists; it does not contact the remote server to prove the token is still accepted. logout does not revoke the remote grant. Agents and tool calls never start browser login. Missing credentials return an explicit authorization-required error for an operator to resolve.

Before an MCP operation, Colossus obtains or refreshes the access token. It does not refresh and retry a tool call whose outcome may already be unknown.

OAuth credential storage¶

Encrypted records are bound to repository, configured server name, endpoint, and active storage key ID. They are re-encrypted after storage-key rotation when the historical key remains available. Changing the workspace identity, server name, or endpoint therefore requires a separate login instead of silently reusing another server's credentials.

Platform-store and encrypted-state failures do not fall back to another store. Plaintext state is selected automatically only for keyless storage or when configured explicitly, and its effective posture is reported by diagnostics and interactive UI.

Selection and bounds¶

allowedTools is required for every server and accepts exactly one of these forms.

Explicit tool names¶

allowedTools:
  - splunk_run_search
  - splunk_get_indexes

Names must be unique and use 1–128 ASCII letters, digits, dots, underscores, or hyphens. Tools published by the server but absent from this list are filtered out.

Explicit selection is recommended for production because a server update cannot make a new tool callable until an operator reviews and adds its exact name.

All discovered tools¶

allowedTools: ["*"]

The wildcard must be the only entry. It cannot be mixed with names, and an empty list or duplicate explicit names is rejected.

Wildcard mode dynamically trusts every current and future valid tool published by that configured server. Colossus still validates tool-name uniqueness, schema validity, description and annotation bounds, pages, argument objects, policy decisions, approvals, results, and audit records. If any wildcard-discovered tool violates the validation bounds, discovery fails closed.

This wildcard selects server-published tools only. It does not widen access.tools.include, authorize the endpoint in sandbox.networkDestinations when using an isolating boundary, grant a credential, or approve mcp.call. Those remain separate trust boundaries; see Access configuration.

Wildcard mode applies only to top-level server configuration. Signed-pack MCP declarations remain stdio/process-only and require explicit tool names.

Fresh schema binding¶

Every call performs live discovery again, finds the selected tool, validates its JSON object schema, validates the supplied argument object, and binds the schema and its SHA-256 hash into the effect request. A schema cached from an earlier mcp tools command does not authorize a later call.

This protects both explicit and wildcard selection from silent schema drift. It also means the MCP server must be available for discovery immediately before invocation.

Risk-auto review¶

When policy requires approval, --approval-mode risk-auto may review a configured top-level mcp.call made by a model or child agent outside workflow lineage. The credential-free evaluator input contains the exact endpoint identity, transport, configured server, tool, bounded description and annotations, fresh schema hash, and validated arguments. Descriptions and annotations are server-provided advisory hints; they are not authority or hard eligibility preconditions.

Both explicit tool selection and allowedTools: ["*"] use the same review rule because the automatic proof binds one exact invocation. A change to the endpoint, server, tool, schema hash, or arguments invalidates that authority. Stdio and Streamable HTTP calls also share review eligibility, while retaining their separate process and network obligations. Only a valid low-risk allow assessment avoids a dialog. Medium, high, uncertain, unavailable, malformed, or unsupported reviews preserve explicit approval, and an ineligible prompt explains why review was skipped.

Server-specific resource limits¶

These values may narrow the deployment sandbox but cannot widen it. JSON bodies, SSE streams, stdio output, parsed tool schemas, and released results remain bounded.

Hard discovery bounds¶

Duplicate tool names, invalid schemas, empty or cyclic cursors, and limit overruns fail closed. mcp servers safely displays allowed_tools: ["*"] so operators can see that dynamic trust is enabled.

Research templates¶

researchTools explicitly maps selected MCP tools into the deep-research MCP lane:

researchTools:
  - tool: splunk_run_search
    title: Splunk security events
    arguments:
      query: "{query}"
      earliest_time: "-24h"

Research templates always remain explicit, even when allowedTools: ["*"]. Merely allowing an MCP tool does not make it a research source. See Deep research for lane selection and evidence behavior.

Configuration and invocation flow¶

Use the commands in this order:

1. Parse configuration without contacting the MCP server:

   colossus --config .colossus/config.yaml config show
   colossus --config .colossus/config.yaml mcp servers
   

2. For OAuth, bootstrap credentials as the operator:

   colossus --config .colossus/config.yaml mcp auth status splunk
   colossus --config .colossus/config.yaml mcp auth login splunk
   

   This direct control-plane operation cannot consume a TUI session acknowledgement. It needs either globally configured danger acknowledgement or exact environment and OAuth-origin grants.

3. Discover released live schemas:

   colossus --config .colossus/config.yaml mcp tools --server splunk
   

4. Invoke one exact tool with a JSON object:

   colossus --config .colossus/config.yaml --approval-mode ask \
     mcp call splunk splunk_get_indexes '{}'
   

Use @path in place of inline JSON to read arguments from a policy-readable file. mcp servers is a safe configuration summary and does not launch or contact the server. Discovery and invocation are separately authorized effects.

Security behavior¶

Configured credential values are hard-redacted from released schemas, results, errors, policy input, diagnostics, and audit evidence. If discovery itself contains one of the configured secret values, Colossus rejects the page rather than releasing it.

The remote client disables ambient proxies and automatic redirects, pins DNS resolution, rejects an unexpected endpoint, and validates exact response media types. Every result remains quarantined until post-effect policy permits release.

An MCP server is still an external authority. Tool descriptions, schemas, and results are untrusted input. Explicit tool selection reduces the consequences of a compromised or unexpectedly upgraded server; wildcard selection intentionally broadens that trust.

Common configuration mistakes¶

Return to the configuration overview.