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. The native remote transport targets MCP 2025-11-25. Stateful sessions are required by default; exact remote declarations may explicitly allow a server that omits Mcp-Session-Id. Legacy HTTP+SSE and 2026-07-28 release-candidate semantics are not enabled.

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 names, or a wildcard mixed with explicit names is rejected. Signed-pack MCP declarations remain explicit-only. 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.

3. Discover live allowed schemas

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

Discovery launches the exact executable or creates a fresh initialized HTTP exchange and returns only selected, validated tool schemas. Stateful remote servers receive best-effort session cleanup; explicitly stateless 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 a distributable executable capability with Packs. Exact MCP configuration fields live in MCP server configuration.