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`).
`--foreground`	With `--transport http`, run the daemon in the current process instead of detaching. Use this as a container’s start command so the daemon is PID 1 and receives `SIGTERM` directly. Writes no state file, so `mcp status` and `mcp stop` do not apply.
`--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.

Health endpoints

The http daemon serves two unauthenticated probe endpoints next to /mcp, for orchestrators such as Kubernetes.

Endpoint	Meaning	Response
`GET /livez`	The process is up and serving HTTP.	`200 {"status": "ok"}`
`GET /readyz`	The service is built and tools can be served.	`200 {"status": "ready", "version": "<canonic version>"}`

Both endpoints skip the auth layer on purpose, so a probe needs no token. They expose only the status and the canonic version. /readyz is deliberately shallow: it makes no connector or warehouse call, so probes never generate warehouse traffic. The stdio transport has no HTTP surface and no probes. Example Kubernetes probes for a daemon listening on port 7474:

startupProbe:
  httpGet: { path: /readyz, port: 7474 }
  periodSeconds: 2
  failureThreshold: 30
livenessProbe:
  httpGet: { path: /livez, port: 7474 }
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readyz, port: 7474 }
  periodSeconds: 5

In a container, start the daemon with canonic mcp start --transport http --host 0.0.0.0 --foreground. Without --foreground the command detaches and returns, so the container would exit right after starting. --host 0.0.0.0 lets the probes reach the pod IP. The official image ships a Docker HEALTHCHECK that calls /livez on port 7474.

`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), 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.

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

`mcp start`

Health endpoints

`mcp stop`

`mcp status`

​mcp start

​Health endpoints

​mcp stop

​mcp status

`mcp start`

Health endpoints

`mcp stop`

`mcp status`