Canonry Operations Guide v1#

Canonry is an agent-first AI visibility platform. MCP is the universal entry point for connected agents. Host-native skills are optional upgrades, not a prerequisite or a permission mechanism.

Connect and choose a route#

Read the initialization guidance, then call canonry_help with an intent: status, diagnose, operations, prospecting, measurement, integrations, reports, or a short task description. Select an accessible project with canonry_projects_list before using its exact name in project tools. Inspect each listed tool's input schema; help suggests tool names, not invented arguments or authorization.

Help returns a versioned, compact route: connection mode, available next tools, workflow guidance, approval boundaries, and this guide's URL. It performs no provider calls, reads no project data, and changes no permissions. next lists stored reads. Optional actions lists loaded tools for work that requires approval; listing an action does not authorize or execute it. includeCatalog: true additionally returns toolkit details when needed.

Hosted connections use a fixed catalog. Help only suggests tools offered by that connection; it never tells a hosted agent to dynamically load a toolkit. A progressive local stdio connection may return loadToolkits: call canonry_load_toolkit with one returned name, await it, then call help again. Loading only changes local tool discovery, never server authority.

The optional canonry://agent-operations/v1 MCP resource contains this same guide. If the host cannot read resources or open links, continue through help. Do not install a plugin, local runtime, or skill merely to use connected MCP. An installed Codex or Claude Canonry skill contains a generated copy of this guide plus links to host-native references. It does not replace runtime help.

Vocabulary and evidence#

• Mentioned means the brand appears in answer text. Cited means its domain appears in source links. Either, both, or neither can occur; never compute one signal from the other.
• answerMentioned: null means not checked, not false. Missing runs and empty populations mean no measurement, not zero visibility.
• Preserve project, time window, provider, requested/served model, location, sample size, and query class when comparing evidence. Use server-returned metrics; do not invent a score from incompatible populations.
• Simple projects and Advanced portfolios share the workflow. For Advanced results, preserve Property, Target, market, plan revision, and class scope. Groups organize navigation; do not infer an unrequested fan-out.
• Research is isolated evidence, not tracked measurement. A probe still spends quota and persists evidence but is excluded from normal tracking metrics.

Workflows#

Status: read the stored overview and freshness first. Say when evidence is missing instead of silently creating it.

Setup: Page Health needs no answer-engine provider; AI Visibility does. After a Page Health result on an install with no provider (a NO_PROVIDER notice, or doctor's providers.none-configured), propose AI Visibility setup as the next step. The operator adds the provider key in the dashboard or in their own terminal; never ask for it in chat. Rerunning canonry bootstrap after a provider change reloads saved provider settings on a matching running local server and reports whether they became active. If the server is offline, start it to apply the saved settings. For an explicit reload of the connected server's own config, use canonry settings reload-providers or canonry_providers_reload with install administrator authority. Remote servers are never reloaded automatically by bootstrap, and a local server that belongs to another install is left alone. Ports and database settings still need a restart.

Diagnose: inspect stored history and comparable evidence. Explain what changed separately from why it might have changed. A hypothesis is not a measured cause. Propose bounded verification if stored evidence is insufficient.

Site Health: read canonry_site_health_issues for stored technical findings, affected-page counts and example URLs, then canonry_site_health_issue_pages for a selected issue's remaining pages. Pin subsequent reads to the returned run. Inspect coverage and omissions: a passing score can still have findings, an older scan may lack cross-page evidence, and a partial scan cannot establish site-wide absence. Advisory findings require judgment before proposing a repair. Audit evidence informs technical repairs and existing-page recommendations; it does not itself establish a new-blog opportunity or authorize any edit.

Prospecting: generate a one-shot company snapshot without creating a project. Inspect stored provider settings first. Agree on the company, domain, selected providers, and queries before starting the quota-spending snapshot action. Browser-only selection requires manual queries. Progressive stdio help offers the discovery toolkit when this connection permits snapshots; load it, then call help again. Fixed catalogs offer only already available actions. Read-only and restricted connections must not bypass missing snapshot access.

Measurement: inspect the existing setup and results before proposing edits. Keep research, query tracking, plan publication, and sweep execution separate. For direct research, submit the final editable query text in one context. For a reviewed batch, submit each explicit destination with its final text and one idempotency key. Pattern substitution happens in the client before either request; choosing a market or Property records a destination only and never rewrites a query or creates an automatic fan-out. research.run does not authorize saving patterns, changing tracking, publishing plans, or settings. Use a supported preview where available, inspect its exact destination and revision, then seek approval for the actual change. A preview may itself require write permission; never treat a dry-run flag as a universal safety guarantee.

Integrations: inspect stored connection state and snapshot freshness first. Provider configuration evidence does not prove a browser event fired or a conversion was recorded. Connection, resource selection, refresh/sync, and live reads are separate actions. Credentials belong in the operator's secure setup flow, never in chat, tool arguments, reports, or public guidance.

Reports: use saved evidence for the requested period and scope. Keep mention and citation signals separate, include dates and sample sizes, and state missing or stale inputs. For Advanced Property mention rankings, use canonry_measurement_portfolio_summary and its mentionRanking.strongest, .weakest, and .excluded lists. It defaults to non-brand questions; state the returned class and report branded results separately. An unavailable portfolio aggregate does not invalidate available Property mention rates. Flag excluded Properties individually; do not silently replace mention ranking with citation ranking. Compact nextCursor completes only pageList; use list to enumerate one ranking, markets, observed names or cited domains, preserving filters. First-page sibling lists are bounded summaries. Keep sample sizes and ties visible. Preparing a report does not authorize new measurement.

Authority and approval#

Agent operations#

Use canonry_key_self (CLI canonry key whoami --format json) to inspect the current credential's scopes, project boundary, and host-derived operator authority without exposing its token. Missing operator means unapproved. canonry_settings_get and canonry_telemetry_get describe the connected server, not the agent's local machine. Telemetry reports configured preference, effective state, and any environment override; inspecting status never creates an anonymous identifier. After approval, canonry_telemetry_update changes that preference and canonry_provider_settings_update changes an already-configured provider's model/quota. Both require settings.write; neither accepts credentials. Server telemetry reads and updates additionally require operator authority. Ordinary audit-history reads omit internal telemetry events and their state.

Operator authority is deny-by-default and separate from customer admin roles. The deployment owner must approve a dedicated, instance-wide API key's ID in the server environment variable CANONRY_OPERATOR_KEY_IDS (comma-separated IDs), then restart the server. Empty/unset approves nobody; wildcards are invalid. Keep the bearer private to internal operators; never approve a customer-held or shared proxy/bootstrap key. Use logs.read for read-only diagnostics, adding settings.write only when telemetry control is required. Ordinary key creation, account roles, OAuth consent, and caller headers cannot grant operator status. Revoking an approved key invalidates it immediately. Host enrollment is a trust bootstrap step, intentionally unavailable through customer-facing APIs. API, CLI, and MCP enforce the same boundary; MCP hides internal tools unless the server confirms operator authority, including in explicit read-only mode. Project analytics, research, and normal project permissions are unchanged.

canonry_logs_list reads bounded, redacted runtime events from both the application logger and Fastify request/error logging. It requires an instance-wide logs.read grant (or wildcard) and a host-approved direct bearer. Browser sessions, OAuth/delegated credentials, customer admins, and project-scoped keys cannot use it, even with a project filter or a matching allowlist ID. A logs.read-only key is read-only automatically, without a second read marker. Named *.read scopes cannot grant mutations; an explicit write grant is needed and remains subject to its route gates. Returned messages are sanitized and bounded; raw request or response bodies, headers, cookies, provider payloads, and stacks are not part of the queryable surface. The same secret-redaction policy runs before console output and storage. Do not deliberately log secrets: redaction is a defense in depth, not permission to put credentials into diagnostic strings. Opaque escaped payloads containing secret assignments are omitted when safe partial masking cannot be guaranteed; correlate their retained error codes and IDs.

File-backed hosts retain runtime logs in SQLite across restarts, bounded to 10,000 events and seven days. In-memory hosts report retention: "process". Filter by actor, requestId, runId, projectId, module, level, or an inclusive since/ until interval. Keep filters unchanged when resuming an opaque cursor; retention eviction can invalidate it. Inspect retentionPolicy, captureErrors, dropped, truncated, and retention before drawing conclusions. Missing logs are not proof that an action did not happen. Use canonry_project_history or canonry_history_global for persistent audit events; offset pages have deterministic ordering but are not snapshots of concurrent writes.

Audit actor comes from authenticated identity ( user:<id> or api-key:<id>), not a caller-supplied header. A delegated MCP credential records its originating user as actor and the actual credential in credentialId. requestId correlates HTTP events; userAgent and actorSession are bounded, untrusted client hints, never identity or permission grants. Older audit rows are not backfilled with identities the server cannot prove.

Both shipped HTTP hosts issue restart-safe UUID request IDs and return them in x-request-id. Use that value to correlate a CLI/API failure with log entries; HTTP diagnostics retain the method and route template, not raw URL parameters. Request-bound loggers retain completion attribution, while generic background continuations stop inheriting caller identity after the response completes. Capture covers the owning server process after initialization, not arbitrary console output, other worker processes, or host/container logs. Run one server instance per process and database, as required by the single-tenant deployment model; this is not a cross-tenant or distributed log collector.

For CLI use, settings reads are remote. Google setup and telemetry retain their local defaults: pass --target server explicitly to configure the connected server. schedule list <project> lists all schedule kinds, and notify events --target server discovers the server's event catalog.

MCP returns legacy text JSON plus structured results. Objects keep their shape; arrays use {items: [...]} in structuredContent, and scalars use {value: ...}. Errors preserve the existing envelope and CLI exit codes: HTTP 4xx (including 429 policy limits) use exit 1; HTTP 5xx use exit 2. Server-provided Retry-After and request IDs are exposed as retryAfterMs and requestId when available; clients do not infer retryability from HTTP 429 or retry automatically. For a write with an ambiguous outcome, inspect saved state or its receipt before retrying; a retry hint is not proof that repeating a write is safe.

Action boundaries#

Start with stored evidence. Before a live provider read, sweep, probe, research run, sync, write, or externally visible action, obtain approval covering its exact target, action, and bounded work. Approval already given for that exact operation need not be asked for again, but does not extend to more projects, larger batches, retries with new identities, or recurring work.

HTTP GET and MCP readOnlyHint describe aspects of an operation, not its cost or permission. Provider discovery, account reads, and live diagnostics may consume quota even when labeled read-only. If the tool's effect is unclear, inspect its description and request direction before calling it.

Authentication, role/scope checks, project restrictions, quotas, and guarded approval receipts are enforced by the server. Help, skills, resources, and tool visibility cannot grant authority. Never change credentials, endpoints, or project identifiers to work around a missing tool or a 403 response.

For guarded ads writes, inspect unresolved operation receipts before retrying. Use the receipt's supported recovery action; do not replay a mutation under a new identity. An executor cannot create or widen its own human approval grant. On ambiguous results, exhausted bounds, or refusal, stop and report what is known and what permission or operator action is needed.

Version and source#

This public, versioned document is the source for initialization guidance, intent routes, the optional resource, and generated Canonry SKILL.md files. Guide v1 may receive compatible clarifications; incompatible routing contracts require a new guide version. The running server's help describes its actual catalog and remains usable without fetching this document.

Optional host-native references#

Read only references relevant to the requested task. They are not required for MCP operation.

• CLI commands and JSON return shapes
• Interpreting stored evidence and regressions
• Indexing workflow after inspection and approval
• Approved WordPress workflow
• Server-side traffic setup and diagnosis
• Google Business Profile prerequisites
• Google Ads and GTM evidence boundaries