Skip to content

MCP

Goal

Configure a local stdio or remote Streamable HTTP MCP server, select explicit tools or opt into dynamic wildcard discovery, and invoke tools without bypassing Colossus policy. Remote HTTP defaults to protocolVersion: auto: discover stable MCP 2026-07-28, then fall back to 2025-11-25 initialization for older endpoints. Select either version explicitly in configuration or Desktop's Protocol version control. The 2026 protocol is sessionless; 2025 requires a session ID unless allowStateless: true is explicitly configured. Stdio retains the 2025 initialization lifecycle. Legacy HTTP+SSE with separate endpoints is unsupported.

Prerequisites

  • For stdio, an MCP server executable at a canonical absolute path.
  • For Streamable HTTP, an exact credential-free endpoint. Isolation requires HTTPS outside exact loopback development; acknowledged full access also accepts canonical non-loopback plaintext HTTP, with no TLS protection.
  • Any secret behind an env:VARIABLE reference.
  • Under an isolating boundary, matching process or network, filesystem, and environment grants. Acknowledged full access supplies ambient resources but does not create the server declaration or tool allowlist.

Steps

1. Add an exact server declaration

Merge this fragment into .colossus/config.yaml:

mcp:
  oauthCredentialStore: auto
  servers:
    local-docs:
      command: /absolute/path/to/mcp-server
      args: [--stdio]
      workingDirectory: /absolute/path/to/repository
      environment:
        API_TOKEN: env:MCP_API_TOKEN
      allowedTools: [search_docs]
      researchTools:
        - tool: search_docs
          title: Internal documentation
          arguments:
            query: "{query}"
      timeoutMs: 30000
      maxOutputBytes: 1048576

Under isolation, add the command to sandbox.executables, its working directory to the appropriate filesystem roots, and API_TOKEN to the allowed environment names. Acknowledged full access supplies those resources but still requires the exact absolute command and credential reference in the server declaration. Configuration stores the reference, not the secret value.

For a remote Splunk endpoint with a static bearer token:

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: ["*"]
      timeoutMs: 30000
      maxOutputBytes: 1048576

Under an isolating boundary, add the exact endpoint origin to sandbox.networkDestinations and SPLUNK_MCP_TOKEN to sandbox.environment. Permit-bound discovery and calls under acknowledged full access need neither duplicate grant; adding them does not constrain ambient authority. allowedTools: ["*"] is deliberately broad: every currently or subsequently published valid tool becomes eligible for normal schema validation, policy, approval, quarantine, and audit. An empty list, duplicate selectors, or "*" mixed with other entries is rejected. Use patterns such as "get_*" or "*_search" to select a narrower set of current and future tools. See tool name patterns. Agent Plugin MCP declarations still require an explicit operator-owned overlay. Set allowStateless: true only when the reviewed remote server intentionally omits Mcp-Session-Id; omit it for stateful servers.

OAuth is an alternative to credentialHeaders:

      oauth:
        clientId: colossus
        clientSecretReference: env:SPLUNK_MCP_CLIENT_SECRET
        callbackPort: 8787
        scopes: [openid, offline_access]

Use colossus mcp auth login splunk; add --manual to paste the final redirect URL in a headless environment. status inspects local token presence and logout removes local tokens without remote revocation. Agents never initiate browser login.

mcp auth login is a direct operator control-plane operation, not a permit-bound MCP turn. It receives ambient environment and OAuth-origin authority only when the effective configuration selects sandbox.backend: danger_full_access and globally sets sandbox.acknowledgeDangerFullAccess: true. A TUI's session-only danger acknowledgement applies to permit-bound discovery and calls, not to this login ceremony. Without the global acknowledgement, grant the client-secret environment name and every actual protected-resource, authorization, and token origin exactly.

2. Inspect configuration without launching

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

This lists configured names and exact allowlists.

At the start of an agent run, Colossus also gives the model a short list of configured MCP source names. It does not connect to the servers to build this list. When the model needs one, mcp.search discovers allowlisted tools and returns at most ten ranked names and short descriptions without their schemas. A search can target one server by its exact configured name. mcp.tools with both server and tool then returns that tool's live schema; mcp.call discovers and validates it again before invocation. Search uses local text matching over tool names, titles, descriptions, and argument names. It does not require an embedding service.

Broad searches report unavailable server names while still returning matches from working servers. A missing stdio executable is shown as available: false in mcp servers and does not stop other servers or the runtime from starting. Remote health is checked when a discovery or call is made.

3. Discover live allowed schemas

colossus --config .colossus/config.yaml mcp tools \
  --server local-docs

Discovery launches the exact executable or negotiates a fresh HTTP exchange and collects all pages on that transport. It returns selected, validated tool schemas. Legacy stateful servers receive best-effort session cleanup; 2026 and explicitly stateless legacy servers have no session to close.

4. Invoke the exact tool

colossus --config .colossus/config.yaml --approval-mode ask \
  mcp call \
  local-docs search_docs '{"query":"authorization"}'

Use @path instead of inline JSON when arguments come from a policy-readable file. MCP invocation is allowed by the sparse allow_all default. With an explicit development access profile it is approval-required; the global --approval-mode ask option lets the noninteractive CLI request that approval before it launches the configured process.

Expected result

Colossus starts only the configured process or contacts the permit-authorized exact HTTP origin, validates the selected schema and input, bounds JSON and SSE output, removes hard secrets, closes the session best-effort, and releases an audited result.

Verification

Confirm that tools list contains only the intended connected MCP operations and that recent audit evidence identifies the exact server and tool without credential values. The maintainer-only live Splunk smoke-test command is documented in Source setup and test tiers.

Failure path

  • Executable denied: configure an exact absolute executable; under isolation also add it and the required working directory to sandbox grants. MCP never uses shell lookup for its configured command.
  • Tool is absent: include the exact discovered name in allowedTools.
  • Environment denied under isolation: allow the variable name and keep its value behind an env:VARIABLE reference.
  • Authorization required: run colossus mcp auth login SERVER; tool calls never trigger interactive login.
  • Network denied under isolation: grant the exact canonical origin. Public * grants remain public-address-only and cannot authorize loopback or private destinations.
  • Output exceeds bounds or is malformed: fix the server; Colossus does not release unbounded or invalid output.

Next step

Package portable skills and MCP declarations with Agent Plugins. Exact standalone MCP configuration fields live in MCP server configuration.