> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcanonic.app/llms.txt
> Use this file to discover all available pages before exploring further.

# canonic mcp

> Control the local MCP daemon.

`canonic mcp` starts, stops, and reports on the local MCP daemon that exposes canonic's capabilities to agent clients. See [Connecting your agent](/mcp-integration/connecting-your-agent) for the client-side setup.

## `mcp start`

Start the local MCP daemon.

```bash theme={null}
canonic mcp start
canonic mcp start --transport http --port 7474
```

| Flag              | Description                                                                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--project`, `-p` | Path to the canonic project root (overrides the cwd walk).                                                                                                                                                                                                         |
| `--transport`     | `stdio` (default, local) or `http` (remote, network-reachable).                                                                                                                                                                                                    |
| `--port`          | Port for the HTTP daemon (default `7474`).                                                                                                                                                                                                                         |
| `--host`          | Host for the HTTP daemon (default `127.0.0.1`).                                                                                                                                                                                                                    |
| `--token-ref`     | Bearer token reference (`env:VAR`) for `--transport http`, overriding/supplementing `mcp.auth.tokens` in `canonic.yaml`.                                                                                                                                           |
| `--suggestions`   | Enable follow-up suggestions in query responses.                                                                                                                                                                                                                   |
| `--tenant`        | Bind a fixed, roleless principal for a `stdio` session, local-development/platform-operator use only. Always logs a warning. Refused (exit `1`) on `--transport http`. See [Tenancy & access control](/concepts/tenancy-and-access-control#--tenant-cli-override). |

With `--transport stdio` (the default), the daemon runs in the foreground over stdio, and the MCP client manages its process lifetime. There's no auth layer, since a local subprocess is inherently process-trusted. If a [tenancy policy](/concepts/tenancy-and-access-control) is active, a `stdio` session has no per-request auth to derive a principal from, so `--tenant <id>` must be passed explicitly.

With `--transport http`, it forks a background uvicorn daemon bound to the given host/port using Streamable HTTP. Because the daemon becomes network-reachable, it **requires** at least one auth mechanism: a bearer token, OAuth 2.1, or both. Configure `mcp.auth.tokens` and/or `mcp.auth.oauth` in `canonic.yaml`:

```yaml theme={null}
mcp:
  auth:
    tokens:
      - client_id: alice
        token_ref: env:CANONIC_MCP_TOKEN_ALICE
    oauth:
      mode: proxy   # proxy | jwt
      issuer_url: https://idp.example.com
      client_id: canonic-mcp
      client_secret_ref: env:CANONIC_OAUTH_CLIENT_SECRET
      base_url: https://canonic.internal.example.com
```

or pass `--token-ref env:SOME_VAR` for a quick one-off token. Starting `--transport http` with neither configured is a hard error. Token clients authenticate with `Authorization: Bearer <token>`. OAuth clients complete the IdP's login flow (`proxy` mode) or present an IdP-issued JWT directly (`jwt` mode). Either way the resolved `client_id` (a token's configured name, or the OAuth subject/email) is recorded on every `query`/`run_sql` answer event for per-user attribution. See the [config schema reference](/reference/config-schema#mcp) for the full `oauth` field list, and [Connecting your agent](/mcp-integration/connecting-your-agent#remote-enterprise-deployment) for the deployment walkthrough.

On first start in a project with no active metric contracts, canonic auto-generates inferred metric contracts from the loaded semantic sources before serving.

## `mcp stop`

Stop the background MCP daemon.

```bash theme={null}
canonic mcp stop
```

## `mcp status`

Report whether the MCP daemon is running.

```bash theme={null}
canonic mcp status
```

Shows the PID, transport, address and auth state (for HTTP, which mechanism(s) are active, e.g. `token, oauth-proxy`), the canonic version, the FastMCP version the daemon runs, and the start time. Warns if the running daemon's version differs from the current CLI version. In that case, restart it with `canonic mcp stop && canonic mcp start`.