Connect an AI agent with MCP

Anectico exposes a remote Model Context Protocol endpoint. An AI agent can investigate customers, Issues, traces, logs, replay, incidents, and LLM cost without copying telemetry into prompts by hand.

Start with read-only access. For the whole loop end to end — connect, discover, investigate, act — see Run an agent without the dashboard; for what a client must support, see MCP client compatibility.

Before the first OAuth connection

An OAuth-capable MCP host can discover Anectico's sign-in service, register its client, and run the browser authorization flow without storing an API key. That flow authenticates an existing Anectico member; it does not create an organization or membership from the access token.

If this is the person's first Anectico access, an organization owner must invite or provision them first. An owner can do that without the dashboard by running anectico invitations create person@example.com --role ROLE_MEMBER. The person then completes the normal Anectico sign-in (or runs anectico login) once and accepts the invitation before reconnecting the MCP host. See Manage an organization and projects for the available roles and invitation lifecycle.

When an operation rechecks access, Anectico repeats OAuth token validation and resolves your current membership and delegated permissions. These checks use your MCP authorization; they do not require a separate dashboard login session. Losing a required permission or presenting an invalid token prevents the operation from continuing with its earlier access.

A valid OAuth token that cannot be matched to an existing membership receives the same generic 403 for every cause. This is intentional: the endpoint does not reveal whether an email, identity, or organization exists. Give support the attempt time and the signed-in address; do not send the token. An operator can distinguish a missing account, an external identity that still needs linking, a conflicting link, and a missing organization membership from the protected audit trail.

Set it up in one command

anectico agent bootstrap does the whole setup: it creates a narrow, project-scoped, expiring key, stores the secret somewhere that is not your terminal history, writes your agent's MCP configuration, and then verifies the new key against the endpoint.

anectico agent bootstrap --project <project-id> --host claude

--host accepts claude, codex, cursor, gemini, or none. For Claude Code and Cursor it also writes the MCP server entry (.mcp.json and .cursor/mcp.json respectively), leaving every other entry in those files untouched.

By default the key is created with the investigate scope bundle and expires in 30 days. Use --scope-profile to pick a different bundle, --scope to add individual scopes, --expires-in to change the lifetime, and --name to label it.

The investigate bundle is read-only, but it is not shallow: alongside logs, traces, metrics and Issues it grants read access to person profile properties, agent run transcripts, and session replay content — the customer detail that makes an investigation possible. If an agent should not see that, name the scopes you want individually with --scope instead of taking the bundle.

It also grants the project inventory read, so an agent can discover the project ids that most other reads take as an argument. Naming scopes individually instead means including projects:read, or the agent has no way to look one up.

The key is bound to your active project (--project, ANECTICO_PROJECT, or the profile default). If no project resolves, the command stops rather than creating a key that can read every project; pass --org-wide when that is genuinely what you want.

Where the secret goes

The secret is never printed to standard output unless you ask for it, so it does not end up in an AI agent's transcript.

--secret-dest	Result
keychain (default)	Stored in your operating system's keychain. On a machine without one, a file with owner-only permissions under the CLI configuration directory.
env-file	Written to --env-file <path> as ANECTICO_API_KEY=… with owner-only permissions. An existing file is never replaced without --force.
stdout	Printed as the only thing on standard output, so it can be captured: KEY=$(anectico agent bootstrap --secret-dest stdout).

The generated MCP configuration refers to the ANECTICO_API_KEY environment variable rather than embedding the key, so the file stays safe to commit. Export that variable in the environment your agent runs in. If your client cannot expand environment variables, re-run with --embed-secret to write the key itself into the configuration file — it is then created with owner-only permissions and must not be committed.

One step is yours: putting the key in the environment

With the default keychain destination the secret is in your keychain and the configuration reads ANECTICO_API_KEY, which nothing sets yet. Until you connect the two, the agent cannot authenticate:

eval "$(anectico agent key env --export)"

anectico agent key env prints ANECTICO_API_KEY=… for the key stored under the current profile, as the only thing on standard output, so it can be evaluated by a shell or appended to the environment file your agent host reads. It prints a secret on purpose — do not run it where the output is recorded. Add --profile to select a different profile's stored key.

The bootstrap report names this step explicitly: it appears in steps as bridge with the status manual, so a successful run never implies the agent is ready when the credential has not reached it yet.

If ANECTICO_API_KEY is already set when you run the bootstrap, the summary warns you: the agent will keep using that existing credential — which is usually an older, broader key — instead of the narrow one just created, until you replace the variable. Neither key is printed; the two are identified by a short fingerprint so you can tell them apart.

What it verifies

The last step connects with the new key and reports how many tools it can see. A key that authenticates but sees zero tools is reported as a failure: mcp:read on its own is served an empty tool list, because every tool also requires the scope of the domain it reads (errors:read, logs:read, traces:read, persons:read, and so on; the MCP tool reference lists each tool's scopes).

Add --json for a single machine-readable object on standard output, with the key id, scopes, expiry, where the secret went, and the verification result. It never contains the secret unless the destination is stdout. The command exits non-zero if any step failed, and a key that was already created is never revoked for you — the report names its id so you can decide.

Create a key by hand

If you would rather do it yourself, create an API key in Settings → Access with mcp:read plus the domain read scopes the agent's job needs, or from the CLI:

anectico apikey create --scope-profile investigate --expires-in 7d

Give the key a name tied to the person, agent, or automation that will use it.

Do not reuse an application telemetry key. Store the MCP key in the client’s local secret or credential configuration and never commit it to a repository.

Endpoint

Configure a remote HTTP MCP server with:

URL:           https://app.anectico.com/mcp
Authorization: Bearer an_...

The connection is scoped to the organization represented by the API key.

Narrowing one connection with a profile

Append ?profile=investigate, ?profile=incident, ?profile=agent-observability or ?profile=admin to the URL to focus what the client gets. A profile can only ever subtract from what your key's scopes already permit — and what it subtracts applies to the whole connection, so a tool it excludes is neither listed nor callable. Your key's authority is unchanged, and connecting without the parameter gives you the full surface again. Use it to keep an agent's tool list short and its attention on one job; mint a narrower key when you want narrower authority. A malformed parameter is refused rather than ignored — an unknown name, an empty value, a whitespace-only value and the same parameter supplied twice each answer 400 with the list of valid names. See the MCP tool reference for what each profile leaves visible.

Where they are served, search and fetch are the two tools to start from: one query across people, issues, logs, accounts and Anectico's own documentation, and one reference resolved to the object it names. Neither survives a profile that admits nothing for it to route to, and they disappear independently:

Profile	search	fetch
none	yes	yes — all seven reference kinds your scopes allow
investigate	yes	yes, but not incident references — get_incident is native to the incident profile and investigate does not inherit it
incident	yes	yes
agent-observability	no — it admits none of the search sources	yes, but agent_run references only
admin	yes — the documentation source only	yes — doc references only

A refusal names the profile and tells you to connect without one, so this is diagnosable rather than mysterious.

Correlating and tracing your agent's calls

The server identifies itself in serverInfo — in the connection result for older clients, and in the _meta of successful responses for clients on the 2026-07-28 protocol. Read that field rather than assuming a value: the version it reports depends on how the build that answered you was produced, and a deployment that carries no release identifier reports the placeholder 0.0.0-unknown rather than inventing one. Do not hard-code either the placeholder or a real version into a client's compatibility check.

If your agent is instrumented with OpenTelemetry, its calls can join the trace Anectico records for them. Send W3C trace context either as ordinary HTTP headers (traceparent, tracestate) or, for clients on the 2026-07-28 protocol that put per-request metadata in _meta, as _meta fields — com.anectico/traceparent and com.anectico/tracestate, or the bare header names. Headers win when both are present.

W3C baggage is filtered before your call reaches a tool. Two keys are accepted, both purely for correlating your own agent's work with what Anectico records:

Baggage key	Meaning
anectico.agent.session_id	The agent session making the calls.
anectico.agent.task_id	The task or job the calls belong to.

Members with any other key are dropped. An accepted member keeps its key and value only — any properties attached to it are stripped — and is dropped entirely if the resulting key=value pair exceeds 256 bytes. From the tool call onward, the two keys above are the only baggage that exists.

Be precise about what that does and does not promise. The filter applies to your tool call and to everything Anectico does to answer it — not to the moment your request arrives. Baggage you send may still appear in Anectico's own diagnostic traces of the request itself, including on requests that are rejected before any tool runs. Treat baggage as ordinary request metadata: send only what you would put in any other header. In particular, it is not a way to tell Anectico who your end user is — identity comes from the credential and from your instrumented application, never from a header on an agent's request.

Tool-list and other list responses carry cache hints (ttlMs, cacheScope). Anectico always sends ttlMs: 0 and cacheScope: "private": the list of tools depends on the scopes of the key that asked for it, so it must not be cached — not by a shared proxy, and not across a change of credential or a change of permissions. Re-list when you need it.

Claude Code

anectico agent bootstrap --host claude writes this configuration for you. To add it yourself:

claude mcp add --transport http anectico https://app.anectico.com/mcp \
  --header "Authorization: Bearer an_..."

Run claude mcp list in a new session to confirm the server is connected. Protect the local client configuration because it contains the header value.

Other MCP clients

Create a remote HTTP server named anectico, use the endpoint above, and set the bearer header through the client’s credential UI or local configuration. The client must support Streamable HTTP.

Verify with a safe question

Ask the agent:

Search for the most recently active customers and explain which Anectico tools you used. Do not change anything.

Then ask a bounded production question such as:

What happened to buyer@acme.example in the last hour? Cite the underlying Anectico evidence.

Tool results include deep links back to the dashboard so you can verify the answer.

Ask for the documentation

The endpoint also serves this documentation, so an agent can look something up instead of guessing it. Ask:

Using Anectico's own documentation, what scope does a key need to read session replay content?

search_docs finds the page and get_doc reads it, both through execute_read_action, and the search/fetch pair covers the same ground for a client that only knows those two. Each search hit has a stable ref that fetch accepts. get_doc takes an optional H2 through H6 heading, which is how to read one endpoint or command group out of a long reference page without pulling the whole thing through the agent's context. An uncapped page body is byte-identical to the body published at anectico.com/docs; repository frontmatter is omitted, and every hit carries the public URL so you can check what the agent read.

Both need docs:read, which every role holds and which discloses nothing about your organization. A key minted without it simply reports the documentation source as unauthorized. The CLI's investigate and incident bundles include it; agent-observability and admin do not. The URL profile agent-observability excludes docs even when the key holds the scope.

get_doc caps its body at 48 KiB. If truncated is true, use the returned outline to request an H2–H6 section or a smaller nested section; omitted content is not summarized. Supply a page slug to get_doc, not the ref accepted by fetch. See Machine-readable documentation for the public Markdown, manifest, llms.txt, and complete-corpus retrieval surfaces.

Add writes only when required

Read access is sufficient for investigation. If an agent must acknowledge alerts, triage Issues, or manage another resource, create a separate key with mcp:write and only the required domain scopes. Scope recipes for agent jobs gives the minimum set per job, and How agent access is enforced explains what a scope grants, how confirmation works, and what "destructive" means on this surface.

When an agent is retired — or a laptop is lost — follow Revoke an agent's access, which is also exact about what a revocation does not reach.

Mutation receipts encode targets[].before_version and targets[].after_version as exact unsigned decimal strings, or null when unavailable. Keep them as strings when preparing a subsequent expected revision; converting through a JavaScript number can round large versions.