canonic mcp

canonic mcp starts, stops, and reports on the local MCP daemon that exposes canonic’s capabilities to agent clients. See Connecting your agent for the client-side setup.

`mcp start`

Start the local MCP daemon.

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.

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 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:

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 for the full oauth field list, and Connecting your agent 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.

canonic mcp stop

`mcp status`

Report whether the MCP daemon is running.

canonic mcp status

Shows the PID, transport, address and auth state (for HTTP, which mechanism(s) are active, e.g. token, oauth-proxy), version, and 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.

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

`mcp start`

`mcp stop`

`mcp status`

​mcp start

​mcp stop

​mcp status

`mcp start`

`mcp stop`

`mcp status`