Connect Local Anytype to Cursor and the Agent Wiki¶

This runbook wires the Anytype desktop Local API to Cursor (MCP + skills) and defines how the markdown agent wiki stays in sync with Anytype without duplicating private data.

Canonical Anytype references:

• Local API (developer preview)
• Anytype MCP — official setup
• API reference / changelog (use this to pick Anytype-Version)

0. Roles: you vs agents¶

Treat the MCP key as integration-scoped: create it in Anytype with a clear label (e.g. cursor-mcp-tools) so you can revoke it without touching other integrations.

1. Preconditions¶

1. Anytype desktop installed and running (Local API ships with the app; offline-capable).
2. Desktop version supports Local API (docs: release 0.46.x and later).
3. Node / npx available on the machine where Cursor launches MCP (so npx -y @anyproto/anytype-mcp can run).

2. Confirm the Local API is reachable¶

The MCP server talks to the OpenAPI HTTP endpoint bundled with the desktop app.

• Default base URL for the desktop app is typically http://127.0.0.1:31009 (see @anyproto/anytype-mcp README if your build differs).
• If you use anytype-cli or another entrypoint, the port may differ (often 31012). Set ANYTYPE_API_BASE_URL in that case (step 5).

Quick check: with Anytype open, from a terminal:

curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:31009/v1/spaces || true

A non-connection error is fine; you mainly want to see whether the port responds vs connection refused. If refused, ensure Anytype is running and check Settings for Local API / developer options per your app version.

3. Create an API key (two supported paths)¶

Path A — Anytype UI (recommended)¶

1. Open Anytype → App Settings → API Keys.
2. Create new → enter label cursor-mcp-tools (or similar).
3. Complete the 4-digit challenge in the desktop app.
4. Copy the key once; Anytype may also offer a copy-paste MCP snippet — use it only as a reference; do not commit it.

Path B — CLI helper from the MCP package¶

npx -y @anyproto/anytype-mcp get-key

Follow the prompts; store the resulting key only in your secret channel (step 4).

4. Pick Anytype-Version (required header)¶

The official MCP config sends an Anytype-Version header alongside Authorization: Bearer …. That value should match the API revision you are coding against.

1. Open the Anytype API changelog.
2. Choose the latest stable date string shown in the official MCP example (e.g. 2025-11-08) or the version your Anytype build documents.
3. If requests fail with version mismatch errors, update this string first before debugging anything else.

5. Put the key in the Keychain (not the repo, not the shell profile)¶

Run this in your own terminal. It asks for the key without echoing it, checks it against the local API, and stores it in the macOS Keychain as an item that trusts no application, so every read shows a Keychain dialog:

make anytype-key-store
make anytype-key-check   # stored? (reads no value)

Optional if not using default desktop port:

export ANYTYPE_API_BASE_URL='http://127.0.0.1:31009'

Rules (SPB-09):

• Never paste the bearer token into mcp.json, rules, skills, wiki, chat logs, or your shell profile. A shell-profile export reaches every agent you start.
• Click Allow (never "Always Allow") on the Keychain dialog when Cursor or Claude Code starts the AnyType MCP. Deny a dialog you didn't expect: it names the reader "security" whoever asks. See README, "Secrets".

6. Cursor MCP config (this repo)¶

Project file: .cursor/mcp.json, generated from [mcp.anytype] in tool-chest.toml by make mcp-config; don't edit it by hand.

It runs scripts/anytype_mcp_launch.py, which reads the key from the Keychain and starts npx -y @anyproto/anytype-mcp with OPENAPI_MCP_HEADERS set in that server's environment only. It also passes ANYTYPE_API_BASE_URL through if you set it.

After editing, reload MCP or restart Cursor, then confirm the Anytype MCP server shows as connected and tools appear.

7. Wire the agent wiki to Anytype (data flow)¶

Space layout (agreed): Three Spaces in one Vault — Agent (agent full MCP R/W), Job Hunt (two Collections; MCP writes only with your approval), Private (no MCP / no agent by policy). Full detail: ../scaffolding/job-hunt-spaces-and-types.md.

Principle: Anytype remains the system of record for graph-shaped PKM and for private_sensitive payloads. The repo markdown wiki is a parallel surface—v1: summaries + anytype:<id>; the Agent Space is the canonical Anytype graph for agent-owned structured objects.

Linking convention (already in agent-wiki/AGENTS.md):

• In wiki frontmatter: related: ["anytype:<object_id>"] (or a dedicated field you prefer — stay consistent).
• In Anytype Project (or equivalent): store wiki_index_id / link to the canonical wiki page slug when you want bidirectional navigation.

Operational loop:

1. Capture → /pkm-capture (or MCP) creates/updates Anytype inbox or typed object.
2. Ingest public-ish material → drop sources in agent-wiki/raw/, run /agent-wiki-ingest.
3. Summarize across both → /pkm-summarize reads Anytype + wiki; respects classification for model surface (local vs cloud).

8. Audit and rotation¶

• Append high-level events to audit-log.md (no secrets): key issued/rotated/revoked, bulk imports, destructive deletes.
• Follow issue-api-key.md for rotation cadence (default 90 days).

9. Verification checklist¶

• Anytype running; Local API port responds.
• API key created with label cursor-mcp-tools (or chosen name).
• make anytype-key-check says the key is stored, and no ANYTYPE_OPENAPI_MCP_HEADERS export is left in the shell profile.
• Anytype-Version matches changelog guidance.
• Cursor MCP shows anytype server connected; at least one search/create tool succeeds in a throwaway space/object.
• Three Spaces exist (Agent, Job Hunt, Private); Private space_id is not used in agent/MCP workflows.
• /pkm-capture dry run: classification chosen before write; audit row appended.
• Wiki page created with anytype:<id> link back to a real object.

10. Troubleshooting¶

11. Optional next steps (later)¶

• Typed object templates in Anytype aligned to schemas/object-types.md.
• Small scripts/ under anytype-integration/ that call the OpenAPI directly for batch jobs (still no secrets in repo).
• Second key for non-Cursor automations (home lab) with narrower label and revocation independent of Cursor.