Canonry

<!-- Generated from docs/agent-operations/v1.md by pnpm guide:sync. Do not edit. -->

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.

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.

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.