Skip to main content
AppendaHome
Sign inDownload

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. For the in-app chat panel, see Agents.

How it fits together

  1. Desktop app runs and unlocks your encrypted workspace
  2. Agent session starts the loopback gateway on 127.0.0.1
  3. MCP sidecar calls /v1/agent-tools/*
  4. 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

Related