Connecting an agent

Any MCP-compatible agent — Claude Code, Claude Desktop, or a custom tool — can connect directly to a drain: reading it for context before starting work, and writing its own entries as it goes. Agent-written entries are attributed via <token name> and appear in the same timeline as everything else, never a separate audit log.

Add the server

Add this to your MCP client's config — Claude Desktop's claude_desktop_config.json, or Claude Code's .claude/settings.json under mcpServers:

{
  "mcpServers": {
    "drains": {
      "command": "npx",
      "args": ["-y", "github:drains-dev/mcp"]
    }
  }
}

No install step — npx fetches it from GitHub on first run.

Get a token

Open a drain, click your avatar in the sidebar → API tokens → create one. Tokens are scoped to your account (not a single drain) and can be revoked at any time from the same menu — see API tokens.

What an agent can do

  • Read and search entries in any drain the token's account can access
  • Create new entries — @mentions and [[ references ]] are parsed the same way they are for a human-typed entry
  • List and manage drain members
  • Update drain metadata (title, description, tags)

See AGENTS.md for the full machine-readable version of this page.