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 secrets in the environment (not in the repo)¶

The MCP server expects a single JSON string in OPENAPI_MCP_HEADERS (see official MCP doc).

Define a shell / launchd / Cursor env variable (name is ours for clarity):

export ANYTYPE_OPENAPI_MCP_HEADERS='{"Authorization":"Bearer YOUR_KEY_HERE","Anytype-Version":"2025-11-08"}'

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, or chat logs.
• Prefer a user-level env file that Cursor inherits when launched from the Dock (macOS: ensure Cursor is restarted after changing ~/.zshrc if you launch it from GUI only — you may need to set env in a parent process or use Cursor’s documented env mechanism).

6. Cursor MCP config (this repo)¶

Project file: .cursor/mcp.json.

It should:

• Run npx -y @anyproto/anytype-mcp (official package name).
• Pass OPENAPI_MCP_HEADERS from ${env:ANYTYPE_OPENAPI_MCP_HEADERS}.
• Optionally pass ANYTYPE_API_BASE_URL if you are not on the default host/port.

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 · LLM wiki (agent full MCP R/W), Job hunt (two Collections; MCP writes only with your approval), Sensitive · Human only (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).
• ANYTYPE_OPENAPI_MCP_HEADERS set in the environment Cursor uses.
• 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 · LLM wiki, Job hunt, Sensitive · Human only); Sensitive 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.