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.

Install as a Claude skill (easiest)

The Drains skill is a thin layer on top of the same MCP server below — it depends on the MCP connection, it doesn't replace it. Installing it sets that connection up for you:

npx skills add https://github.com/drains-dev/claude-plugin --skill drains

You'll still need a token (below) — set it asDRAINS_API_TOKEN in your environment.

Add the server manually

Skip the skill and configure this MCP server directly — needed if you're on a different MCP client, or want to wire it up yourself. 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"],
      "env": { "DRAINS_API_URL": "https://drains.dev", "DRAINS_API_TOKEN": "<your-token>" }
    }
  }
}

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.