> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect external tool servers to Comis with the Model Context Protocol

MCP (Model Context Protocol) lets Comis agents use tools exposed by external
servers. Comis does not bundle MCP servers; you choose, configure, and operate
the servers your agents may access.

<Warning>
  A stdio MCP server runs as a local process and is not a security boundary. Vet
  the server and its installation command, grant only the credentials it needs,
  and prefer a pinned package or executable from its publisher.
</Warning>

## How MCP works in Comis

* Comis connects to enabled servers when the daemon starts. One failed server
  does not prevent the daemon or other MCP servers from starting.
* Tools are discovered from each connected server. Comis tracks them as
  `mcp:server-name/tool-name` and exposes the LLM-safe callable name
  `mcp__server-name--tool-name` to agents.
* Only tools from currently connected servers enter the agent tool set. They
  disappear while a server reconnects and return after discovery succeeds.
* An involuntary disconnect, keepalive failure, or repeated client error starts
  automatic reconnection. The default is up to five attempts with jittered
  exponential backoff; an explicit disconnect is not retried.

## Configure a server

<Steps>
  <Step title="Store any required credential">
    Secret names must start with an uppercase letter and otherwise use only
    uppercase letters, digits, and underscores. This command opens a hidden
    prompt and stores the value in the configured credential backend, which is
    encrypted by default:

    ```bash theme={}
    comis secrets set MCP_SERVICE_TOKEN
    ```

    See [Secrets Management](/security/secrets) for non-interactive input and
    storage modes.
  </Step>

  <Step title="Add an array entry to config.yaml">
    `integrations.mcp.servers` is an array. Every entry needs a unique `name`
    and the fields required by its transport.

    ```yaml theme={}
    integrations:
      mcp:
        servers:
          - name: local-tools
            transport: stdio
            command: node
            args:
              - /absolute/path/to/mcp-server.js
            env:
              SERVICE_TOKEN: ${MCP_SERVICE_TOKEN}
            enabled: true
    ```

    Replace the command and arguments with the server publisher's instructions.
    Comis resolves `${MCP_SERVICE_TOKEN}` through its secret manager when loading
    the configuration; the secret value does not need to appear in the YAML.
  </Step>

  <Step title="Restart and verify">
    Configuration-file entries are loaded at daemon startup.

    ```bash theme={}
    comis daemon stop
    comis daemon start
    comis mcp list
    comis mcp status local-tools
    ```

    You can also inspect servers in the web UI under **MCP Servers**.
  </Step>
</Steps>

## Transports

| Transport | Use                                         | Required field | Default concurrency |
| --------- | ------------------------------------------- | -------------- | ------------------- |
| `stdio`   | Local process started by Comis              | `command`      | 1                   |
| `http`    | Remote Streamable HTTP server               | `url`          | 4                   |
| `sse`     | Remote server that only supports legacy SSE | `url`          | 4                   |

`maxConcurrency` overrides the transport default. For stdio, keep the default
unless the server explicitly supports parallel tool calls. Comis can infer
`stdio` from `command` or `http` from `url` when `transport` is omitted, but
setting it explicitly makes shared configuration easier to review.

### Remote server example

Use `http` for current remote servers. Custom headers are supported by `http`
and `sse`; they are ignored for `stdio`.

```yaml theme={}
integrations:
  mcp:
    servers:
      - name: remote-tools
        transport: http
        url: https://mcp.example.com/mcp
        headers:
          Authorization: "Bearer ${MCP_SERVICE_TOKEN}"
        enabled: true
```

Use `sse` only when the server requires the legacy transport:

```yaml theme={}
integrations:
  mcp:
    servers:
      - name: legacy-tools
        transport: sse
        url: https://legacy.example.com/sse
        enabled: true
```

## Secret references

Use `${UPPERCASE_NAME}` anywhere an MCP `env` or `headers` string needs a
stored value. The same syntax can be embedded in a larger string, such as the
`Authorization` header above. A missing reference is reported instead of
starting the server with an unresolved placeholder.

For stdio servers, Comis passes a scrubbed baseline environment plus the
explicit `env` entries in the server configuration. It does not copy every
daemon environment variable into the child process.

## Operate connections

The CLI exposes the live MCP connection state:

```bash theme={}
comis mcp list
comis mcp status remote-tools
comis mcp reconnect remote-tools
```

Additional lifecycle commands are intentionally distinct:

| Command                        | Effect                                                   |
| ------------------------------ | -------------------------------------------------------- |
| `comis mcp test <name> ...`    | Probe a command or URL without persisting it             |
| `comis mcp connect <name> ...` | Connect and persist a simple command- or URL-based entry |
| `comis mcp disconnect <name>`  | Disconnect and remove the persisted entry                |

Agents with admin trust can use `mcp_manage` for `list`, `status`, `connect`,
`disconnect`, and `reconnect`. Connection-changing actions pass through the
approval gate. A newly connected server's tools become callable on the next
message because the active tool set is fixed for the current turn.

See the [configuration reference](/reference/config-yaml) for MCP's place in
the broader Comis configuration.

<CardGroup cols={3}>
  <Card title="Config Reference" icon="file-code" href="/reference/config-yaml">
    MCP configuration structure and core fields
  </Card>

  <Card title="Secrets Management" icon="key" href="/security/secrets">
    Store and reference credentials
  </Card>

  <Card title="Tool Policy" icon="shield-halved" href="/skills/tool-policy">
    Control which tools agents may use
  </Card>
</CardGroup>