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 end to end; for what a client must support, see MCP client compatibility. When an answer is about one thing you can open, the result carries a link to a read-only proof page.

Choose the next agent workflow

After connecting, use the skill pack to find the job, and the scope recipes to choose its access. For ongoing work:

• Event delivery defines signed wake events, receiver verification and delivery receipts.
• Charts in chat defines inline results, supported pictures and evidence fallback.
• Agent budgets defines accepted-operation and covered expenditure controls.
• Plan headroom defines approval capacity and monthly automated work.
• Write recovery recovers an earlier result after a lost reply.
• Person export and person erasure define the privacy workflows.

Connect with sign-in and consent

Point your OAuth-capable MCP host at https://app.anectico.com/mcp. The host discovers the sign-in service and opens authorization. You can sign in there directly; you do not need to open the Console first. Signing up here creates your sign-in identity. Your personal workspace and default project are created when you approve the first connection. Denying approval or closing the consent page does not create them. Accept an invitation to connect to a team's workspace.

Review the client's name and host, including the redirect destination. A registered client's name is unverified; a loopback destination sends the authorization back to software on your computer. Choose one workspace and uncheck permissions the agent does not need. Keep mcp:read for reads and approve offline access if the host needs to refresh its session.

OAuth grants read permissions only. Writes need an owner-created API key with explicit write permissions. A request for write permissions through OAuth is refused with invalid_scope.

Your first project read may briefly return WORKSPACE_NOT_READY. It is retryable: wait for the retry delay in the result (currently one second) and repeat the read. The REST equivalent is 503 workspace_not_ready with Retry-After: 1.

Every approval creates a separate connection, even for the same client and workspace. Effective access is limited by your current workspace role, supported agent permissions, and the permissions you approved. Revoking one approval leaves other approvals working. Removing workspace membership also stops the affected connections.

Revoke an agent's access

In the Console, open Agents and keys (/agents). Review the client and host, workspace, recorded permissions, creation time, last use, and status. Select Revoke, check the confirmation, then select Revoke access. Administrators with members:write can select Everyone's connections to review and revoke other people's approvals in the current workspace. See The Console.

Or sign in as a person with the CLI:

anectico auth connections list
anectico auth connections list --org-wide --json
anectico auth connections revoke <id> --yes
anectico auth connections revoke <id> --org-wide --yes

Use --limit and --offset to page through the list. Connection management requires human login; API keys and connected agents cannot call it. If ANECTICO_API_KEY is set, unset it to use your saved human login. Revocation blocks the next MCP request and further token issuance for that approval, including refresh and any unredeemed code. Reconnecting requires a new approval.

Set it up in one command

anectico agent bootstrap connects one agent host to one project, and it succeeds only when that host can use the result. It creates a narrow, project-scoped, expiring key, keeps the secret out of your terminal history and out of any file you commit, merges the Anectico server into the host's MCP configuration, installs the Anectico skills, and then checks the setup the way the host will use it. The Console shows the same commands on Home, under Connect your agent, for every host except Muse Code.

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

--host is required and accepts claude, codex, cursor, gemini and muse. Inside Claude Code the host is detected and the command says so; no other host can be told apart reliably, so a missing host is refused with the list rather than guessed. By default the key is created with the investigate scope bundle, including model costs and stored evaluation scores, and expires in 30 days. It changes no settings and runs no paid evaluation. Use --scope-profile to pick a different bundle, --scope to add individual scopes, --expires-in to change the lifetime, and --name to label it.

What each host gets

Host	Configuration file (the default is in bold)	How the entry gets the key
Claude Code	.mcp.json in the project. Claude Code keeps user-level servers in ~/.claude.json (%USERPROFILE%\.claude.json on Windows), a file it rewrites itself, so --config-scope user is refused and the command prints claude mcp add --scope user … instead.	A header helper: Claude Code runs anectico agent key header each time it connects and the key stays in your credential store. With --credential env, ${ANECTICO_API_KEY}.
Codex	~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows; $CODEX_HOME/config.toml when that is set). A project .codex/config.toml is read only in a project you have marked as trusted.	bearer_token_env_var = "ANECTICO_API_KEY".
Cursor	.cursor/mcp.json in the project, or ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json on Windows) with --config-scope user.	${env:ANECTICO_API_KEY}, Cursor's own syntax.
Gemini CLI	~/.gemini/settings.json (%USERPROFILE%\.gemini\settings.json on Windows; under $GEMINI_CLI_HOME when that is set), or .gemini/settings.json in the project with --config-scope project.	${ANECTICO_API_KEY}.
Muse Code (not tested on a real install)	~/.config/muse/settings.json. This is the only file, so there is no project scope.	${ANECTICO_API_KEY}. A literal key is never written.

Muse Code has not been tested on a real install. The command is written from Meta's documentation of 10 October 2026. The file that Muse Code reads must contain "schema_version": 1. A new file gets that line. If your file has a different version, or none, the command stops and leaves it as it is. The entry is written with "mode": "optional", so if Anectico is down, Muse Code skips the server and warns you instead of stopping your whole run. After the command, start muse and run /mcp. The anectico server and its tools should be listed. See MCP client compatibility for what has and has not been checked.

Only the anectico entry is touched. Every other server, setting, comment and indentation level in the file is left exactly as it was, and the first time the file changes a copy is kept beside it with the suffix .anectico-backup (owner-only). A file that is empty, or has "mcpServers": null, is treated as having no servers. A file that is malformed, read-only, a symbolic link or otherwise unsafe to edit is refused with its path and the line and column of the problem, before any key is created.

Gemini CLI loads no MCP server in a folder it does not trust, and Claude Code asks you once to approve a server found in a project's .mcp.json; the command tells you what to do for the host you chose.

The key is never written to a file you commit

The entry refers to the key; it does not contain it. Which reference depends on the host (the table above), and every one of them keeps the key out of version control. --credential embed writes the literal key instead, only into a user-level file (so it needs --config-scope user), created with owner-only permissions, for a host launched from somewhere that does not inherit your shell's variables. Muse Code does not accept it: the key is only ever a ${ANECTICO_API_KEY} reference.

See the change first, and undo it

--dry-run shows the file, the exact entry and the skills folder, and changes nothing. No key is created and nothing is sent.

anectico agent bootstrap --project <project-id> --host muse --dry-run

anectico agent remove --host <host> --yes takes the anectico entry out of the host's file and leaves everything else. It does not delete your key or the skills. Revoke the key with anectico apikey revoke, and remove the skills with anectico skill remove <host> --yes. Muse Code and Codex read the same skills folder, so that removes them for both. Add --dry-run to see what would be removed.

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, after the setup has been verified. An existing file is never replaced without --force.
stdout	Printed as the only thing on standard output once the setup works, so it can be captured: KEY=$(anectico agent bootstrap --host codex --secret-dest stdout).

"Ready" means the host can use it

After writing the configuration the command reads it back the way the host will, and makes one authenticated MCP call with exactly the URL and headers that host will send. It exits 0 only if that works. Otherwise it exits non-zero, says what failed and what to do, and undoes what it did: the configuration is restored, the previously stored key is put back, and a key this run created is revoked, so a failure never leaves a live key behind. Running the command again reuses the key that is already stored for the profile instead of creating a second one, and writes nothing if the configuration is already right.

For a host that reads the key from an environment variable (Codex, Cursor, Gemini CLI, Muse Code, or Claude Code with --credential env), the key must be in the environment of the shell that starts the host. Until it is, the command exits 3 with the status needs_environment, proves the rest of the setup with the stored key, and prints the line that finishes it:

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

In PowerShell: anectico agent key env --shell powershell | Invoke-Expression. Start the host from that shell, then confirm with anectico agent doctor --host <host>. anectico agent key env prints the secret on purpose, so do not run it where the output is recorded. Cursor only sees variables set where it was launched, so start it from that shell (cursor .), not from the Dock or Start menu.

If ANECTICO_API_KEY is already set to a different credential when you run the command, the host will use that one instead of the new key; the summary warns you, naming both by a short fingerprint (never the key).

The command checks that the URL in the host's file is the endpoint your CLI profile points at, and sends the key only there, over HTTPS (or HTTP to your own machine), never following a redirect. It never runs a command found in a configuration file.

Add --json for a single machine-readable object on standard output with the status, the diagnosis, the key id, the files written, and the steps taken. It never contains the secret unless the destination is stdout.

Check a setup later

anectico agent doctor --host claude

doctor changes nothing. It finds the host's configuration, reads it back, resolves the key the way the host will, makes the same authenticated call, and compares the key's scopes with what each skill requires. Its diagnosis is one of: config_not_found, entry_missing, config_malformed, entry_disabled, key_not_stored, needs_environment, key_rejected, key_revoked, key_expired, scope_too_narrow, endpoint_mismatch, endpoint_unreachable, tls_error, helper_not_found, or ok. Exit code 0 is ready, 3 means the host has no usable credential, 4 means the key is too narrow, 5 means the configuration is missing, and 1 is anything else.

Both bootstrap and doctor end with a list of the skills and what the key can do for each one:

Skills with this key:
  anectico-triage-issue: works
  anectico-incident: needs incidents:read, incidents:respond, incidents:write, mcp:write for a complete answer (see `anectico skill show anectico-incident`)

The list is information, not a refusal. bootstrap still succeeds, and doctor still exits 0 while at least one skill works. A skill that needs more does the parts it can and says which part it could not do. To give it the rest, create a key with those scopes; Skills lists the scopes and the key bundle for each skill. doctor reports scope_too_narrow only when no skill can be used with the key at all. With --json the same list is the skills array. The default key covers every skill that only reads, including the agent fleet review. Its llm:read and evals:read scopes read model costs and stored quality scores. They do not run an evaluation.

A key that authenticates but sees zero tools is reported as scope_too_narrow: 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).

Sign in with your browser instead of a key

anectico agent bootstrap --project <project-id> --host cursor --auth oauth

This writes the same entry with no key and creates none. The CLI checks that the endpoint offers a complete sign-in, and the browser sign-in itself happens the first time the host connects: run /mcp in Claude Code, codex mcp login anectico, /mcp auth anectico in Gemini CLI, muse mcp login anectico for Muse Code, or choose Connect on the server in Cursor. A connection made this way is for read workflows; anything that changes data needs a key you create on purpose.

Create a key by hand

If you would rather do it yourself, create an API key in the Console under Agents and keys (/agents) 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, refer to the key by environment variable so it stays out of your shell history and out of the file:

claude mcp add --transport http --scope project anectico https://app.anectico.com/mcp \
  --header 'Authorization: Bearer ${ANECTICO_API_KEY}'

Run claude mcp list in a new session to confirm the server is connected.

Codex and other MCP clients

anectico agent bootstrap --host codex (or cursor, gemini or muse) writes the configuration for you. To add it yourself, refer to the key by environment variable:

codex mcp add anectico --url https://app.anectico.com/mcp --bearer-token-env-var ANECTICO_API_KEY
gemini mcp add --transport http --scope user anectico https://app.anectico.com/mcp \
  -H 'Authorization: Bearer ${ANECTICO_API_KEY}'

Cursor has no command for this: add "anectico": {"url": "https://app.anectico.com/mcp", "headers": {"Authorization": "Bearer ${env:ANECTICO_API_KEY}"}} under mcpServers in .cursor/mcp.json.

Muse Code has no command for this either. Add this under mcp_servers in ~/.config/muse/settings.json, a file that must also contain "schema_version": 1:

"anectico": {
  "transport": "streamable_http",
  "url": "https://app.anectico.com/mcp",
  "headers": { "Authorization": "Bearer ${ANECTICO_API_KEY}" },
  "mode": "optional"
}

For any other client, 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.

Hosts that call from the vendor's own servers are described in Connect ChatGPT, Connect Grok and Connect Muse. None of them has been run against Anectico yet; MCP client compatibility records what has.

Ask your agent

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 and give me a link I can open.

Job	MCP tool or action	CLI command
Look across people, issues, logs, accounts and documentation with one query	search	anectico search unified
Resolve one reference from a hit or a citation to its object	fetch	none
Read a documentation page	get_doc	none
Find a documentation page	search_docs	none
Discover the read and write actions your key can use	list_read_actions, list_write_actions	none
Check that the endpoint answers for your key	none	anectico mcp verify
List the keys in use, or revoke one	list_api_keys, revoke_api_key	anectico apikey list, anectico apikey revoke

The CLI has no command for documentation pages. anectico docs prints the CLI's own command manifest instead. The evidence in each result is a citation that fetch resolves.

When an answer is about one thing you can open — a person, an issue, a trace, an agent run, an incident, a dashboard, a session replay or an analytics result — the tool result includes a link to a read-only proof page in the Console, so you can check the answer yourself. The link always names the project that thing belongs to, so you get it whether or not your connection is tied to one project. A list or a search has no page of its own; each row in it that is one such thing carries its own link. An answer that cannot name one project has no link.

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.

Review a connection request

When connecting an agent, review its name and the address it will return to. A client name marked Unverified is supplied by the application. A loopback address returns to a local application on your device; approve only when you started that connection.

Choose the workspace you want the agent to access, then uncheck any permissions you do not want to share. The checklist only offers permissions available to you in that workspace. Refreshing a connection cannot add permissions you did not approve. Each approval creates a separate connection, so two approvals can connect the same agent to different workspaces. Deny returns to the client without granting access. You can revoke a connection from your account later.

Capacity during approval

A new OAuth approval checks the workspace's plan allowance before granting access. Follow that guide's cleanup, downgrade and capacity-refusal remedies. Temporary consent checks can return temporarily_unavailable; preserve an existing valid refresh credential and follow connection recovery.