Skip to main content
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.
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:
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.

Editing a project while the daemon runs

By default the daemon serves the project it loaded at startup. A deployment decides which definitions are live, so editing canonic.yaml, contracts/ or semantics/ on a running daemon changes nothing until it restarts. Knowledge pages are the exception: they are read from disk on every request. The daemon still notices. contract_info returns project_files_changed: true once the contents of those files differ from what the daemon serves. A file that was only touched, or edited and then reverted, does not count. Compare project_fingerprint with the output of canonic status to see which state a daemon runs. The daemon also logs a warning the first time it sees a change. To have the daemon follow edits instead, set project.reload: auto in canonic.yaml or start it with --reload (--no-reload forces the default). This suits a local server that an agent client started and that outlives an edit. Before it serves a request, the daemon compares the modification time and size of the watched files with what it loaded. When one changed, it loads all three again, so an edit takes effect on the next request.
  • A request that has started finishes on the definitions it started with. The new ones apply from the next request on.
  • If the edited files do not validate, the daemon keeps serving the previous definitions and adds a warning that names the failing file to the warnings of query and compile_query. Fixing the file clears the warning. The broken files are not parsed again until they change.
  • A new connections entry in canonic.yaml is picked up, but settings the daemon reads once at startup need a restart: the reload mode itself, the MCP auth mechanism, the host and port, and the event log location.

Health endpoints

The http daemon serves two unauthenticated probe endpoints next to /mcp, for orchestrators such as Kubernetes. 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:
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.

mcp status

Report whether the MCP daemon is running.
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.