Connect with MCP

The MCP sidecar talks to Appenda's local agent gateway over loopback HTTP. Tool names and schemas match the Table API preview — different transport, same contracts.

How it fits together

Desktop app runs and unlocks your encrypted workspace
Agent session starts the loopback gateway on 127.0.0.1
MCP sidecar calls /v1/agent-tools/*
Agents receive appenda.* tools in their tool list

Cursor

Add Appenda to your MCP config while the desktop app is running. The bundled sidecar discovers the gateway profile written per agent thread.

{
  "mcpServers": {
    "appenda": {
      "command": "appenda-mcp",
      "args": ["serve"]
    }
  }
}

Exact binary path depends on your install — use the path shown in Appenda agent settings after your first thread connects.

Codex & Claude Code

Use the official ACP adapters with Appenda's MCP registration. Start an agent thread in the desktop app, then prompt — the runtime ensures the session is ready before tool calls.

Session security

Bearer token + X-Appenda-Agent-Session on each gateway request (per-thread profile, never commit tokens)
Loopback host only — not a public integration surface
Filesystem and shell tools are disabled for agents

Debugging

appenda.health — gateway reachability
Truncated JSON mid-response usually means the payload exceeded the 256 KiB cap — use count_rows or count_only: true on search first
Desktop must stay open with the workspace unlocked