# Configuration (/aiway/mcp/configuration)



The MCP connector runs on KubeMQ's [shared HTTP server](/connectors/concepts/shared-http-server) and is **enabled by default**. Configuration is minimal: a tool-execution timeout and an origin-validation allow-list. This page lists every `McpConfig` field with its verified default and shows how to set each one through TOML, environment variables, and Docker.

## Configuration fields [#configuration-fields]

These are the `McpConfig` fields and their defaults, taken verbatim from `kubemq-server`. All three connectors share the HTTP server's CORS, auth, traffic-gate, and TLS settings — those live in [Shared HTTP server](/connectors/concepts/shared-http-server) and [Auth & security](/connectors/reference/auth-and-security), not here.

| Field                | Type       | Default    | Description                                                                                                                                                                                 |
| -------------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Enable`             | `bool`     | `true`     | Whether the MCP connector is mounted. Enabled by default — set to `false` to turn it off.                                                                                                   |
| `ToolTimeoutSeconds` | `int`      | `300`      | Server-side timeout applied to each tool execution. A tool that exceeds this window returns a tool error (`isError: true`). Must be positive when the connector is enabled.                 |
| `TrustedOrigins`     | `[]string` | `["auto"]` | Origins permitted by the connector's `Origin`-header validation. `auto` allows localhost variants and the server bind address; `*` allows all; an explicit list permits only those origins. |

<Callout type="info">
  `ToolTimeoutSeconds` (default `300`) is the **server-side** tool-execution budget. It is independent of any client-side HTTP timeout and of the per-call `timeout_seconds` argument on tools like `command_send`, `query_send`, and `agent_send`, which is itself capped at `300`.
</Callout>

## Enable / disable [#enable--disable]

The MCP connector is **enabled by default**. Start `kubemq-server` and `POST /mcp` is live — no `=true` flag is required.

To **disable** it, set its enable env var to `false`:

<RunKubeMQ variant="disable" ports="[9090, 50000]" env="{ CONNECTORSMCP_ENABLE: 'false' }" />

<Callout type="warn">
  The disable variable is `CONNECTORSMCP_ENABLE` — there is **no underscore** between `MCP` and `ENABLE`. The name is generated by snake-casing the dotted config key `Connectors.MCP.Enable`; because `MCP` has no lowercase letters, the transform inserts no separator and the segments join. This differs from older KubeMQ docs that described MCP as off-by-default and instructed enabling with `=true` — that framing is stale. See [Shared HTTP server → enable model](/connectors/concepts/shared-http-server#enable-model-on-by-default) for the full algorithm.
</Callout>

## TOML configuration [#toml-configuration]

Set the fields under a `[Connectors.MCP]` table in `config.toml`:

```toml title="config.toml"
[Connectors.MCP]
Enable = true
ToolTimeoutSeconds = 300
TrustedOrigins = ["auto"]
```

## Environment variables [#environment-variables]

Each config field binds to an environment variable derived from its dotted key. The dots are stripped, the remainder is snake-cased and upper-cased, so `Connectors.MCP.ToolTimeoutSeconds` becomes `CONNECTORSMCP_TOOL_TIMEOUT_SECONDS`.

| Variable                             | Config field                        | Default | Description                                                |
| ------------------------------------ | ----------------------------------- | ------- | ---------------------------------------------------------- |
| `CONNECTORSMCP_ENABLE`               | `Connectors.MCP.Enable`             | `true`  | Enable (default) or disable (`false`) the MCP connector.   |
| `CONNECTORSMCP_TOOL_TIMEOUT_SECONDS` | `Connectors.MCP.ToolTimeoutSeconds` | `300`   | Server-side per-tool execution timeout, in seconds.        |
| `CONNECTORSMCP_TRUSTED_ORIGINS`      | `Connectors.MCP.TrustedOrigins`     | `auto`  | Comma-separated origin allow-list for `Origin` validation. |

```bash title="env.sh"
export CONNECTORSMCP_ENABLE=true
export CONNECTORSMCP_TOOL_TIMEOUT_SECONDS=300
export CONNECTORSMCP_TRUSTED_ORIGINS=auto
```

<Callout type="info">
  The `Origin` allow-list set here is an MCP-specific check layered on top of the shared HTTP server's CORS middleware. For how `auto`, `*`, and explicit origins are evaluated — and the `-32010` error returned on a rejected origin — see [Auth & security](/connectors/reference/auth-and-security).
</Callout>

## Docker [#docker]

Pass the same variables to `docker run`. This example keeps MCP at its default-on state and raises the tool timeout:

<RunKubeMQ ports="[9090, 50000]" env="{ CONNECTORSMCP_TOOL_TIMEOUT_SECONDS: '600' }" />

The connector is served because `Enable` defaults to `true`; to turn it off, add `-e CONNECTORSMCP_ENABLE=false` as shown in [Enable / disable](#enable--disable) above.

## Client protocol settings [#client-protocol-settings]

The settings above are server-side. When a client opens a session it negotiates the protocol in the `initialize` handshake. KubeMQ expects protocol version `2025-11-25`, a `clientInfo` object, and an empty `capabilities` object — capabilities are server-driven.

| Setting          | Value               | Description                                                                                                     |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| Protocol version | `2025-11-25`        | MCP protocol version sent in the `initialize` request and echoed in the `MCP-Protocol-Version` response header. |
| Client info      | `{ name, version }` | Identifies the client to the server.                                                                            |
| Capabilities     | `{}`                | Empty object — the server advertises its own capabilities in the response.                                      |

```json title="initialize.json"
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  }
}
```

The server replies with its own `protocolVersion`, `capabilities`, `serverInfo`, and a `sessionId` under `result._meta`. The handshake and session reuse are covered in depth in [Session management](/aiway/mcp/guides/session-management).

## Related [#related]

<Cards>
  <Card title="Shared HTTP server" href="/connectors/concepts/shared-http-server" description="Port 9090, middleware chain, and the enable-model env-var algorithm." />

  <Card title="Getting Started" href="/aiway/mcp/getting-started" description="Run KubeMQ and call your first MCP tool." />

  <Card title="Session management" href="/aiway/mcp/guides/session-management" description="Complete the initialize handshake and reuse the session ID." />

  <Card title="Authentication" href="/aiway/mcp/guides/authentication" description="Authenticate MCP requests and configure trusted origins." />
</Cards>