MCP Server (AI Tools)

AnvilBase ships an MCP (Model Context Protocol) server (@glesumdev/anvilbase-mcp) so MCP-capable AI coding tools can operate your deployment directly: create projects, run DDL and SQL, manage RLS, secrets, users, and edge functions, drive queues, cache, and cron, and read tables — all from inside the assistant.

What it can do

The server exposes 63 tools over stdio, covering:

• Projects — list/create/get/delete.
• Schema — list/create/drop tables, add columns, list extensions, fetch API docs.
• Database — run_sql (data-plane; requires the service-role key), apply and list migrations.
• Data — rest_query (data-plane; requires the service-role key).
• RLS — list/create/drop policies, status, and test_rls.
• Secrets — list/create/delete.
• Users — list/create/delete.
• Keys — rotate API keys (rotate_api_keys).
• Functions — list/get/deploy.
• Webhooks — attach/detach the row-change trigger to user tables and list database-webhook attachments.
• Queues (PGMQ) — create/list/drop queues, send (single + batch), read/pop/ack, archive/list-archived/replay, and queue metrics.
• Cache (Valkey) — get/set/del, incr/decr, expire/ttl, exists, mget/mset, scan.
• Cron — schedule/list/delete jobs and inspect recent runs.
• Email / SMTP — read and configure per-project SMTP settings.
• Admin — platform stats and audit-log listing.

Quick setup

anvilbase mcp setup            # interactive: pick your tools, project or global scope
anvilbase mcp status           # show what's configured + whether the token resolves
anvilbase mcp remove --agent cursor   # unregister

setup writes each tool’s config to launch the server via npx -y @glesumdev/anvilbase-mcp. It never writes your token to disk — it references the ANVILBASE_TOKEN environment variable.

Non-interactive

anvilbase mcp setup --agent claude-code,cursor --global \
  --url https://your-host --yes

The token

The server authenticates to your control plane with a bearer token — a PAT (anvilbase_pat_…) or the admin token. Export it in the shell that launches your tool:

export ANVILBASE_TOKEN=anvilbase_pat_…    # add to ~/.zshrc / ~/.bashrc to persist

• Terminal-launched tools (zed ., warp, claude) inherit your shell env.
• GUI-launched tools (Dock/Spotlight) don’t see your shell — put the token in the config’s env block instead (it’s written to that file).

Optional: ANVILBASE_SERVICE_ROLE_KEY enables the data-plane tools (run_sql, rest_query).

Supported tools

Claude Code, Cursor, Codex CLI, Windsurf, VS Code (Copilot), Zed, and Warp. Codex / Windsurf / Cursor inherit your shell env, so export ANVILBASE_TOKEN before launching. Zed (context_servers in settings.json) and Warp (.warp/.mcp.json) get a real config file written and auto-detected.

Claude Code

anvilbase mcp setup --agent claude-code (add --global), or add to ./.mcp.json:

{
  "mcpServers": {
    "anvilbase": {
      "command": "npx",
      "args": ["-y", "@glesumdev/anvilbase-mcp"],
      "env": {
        "ANVILBASE_URL": "https://your-host",
        "ANVILBASE_TOKEN": "${ANVILBASE_TOKEN}"
      }
    }
  }
}

The anvilbase server then shows under /mcp with anvilbase_…-prefixed tools.

Zed

Key is context_servers (not mcpServers):

{
  "context_servers": {
    "anvilbase": {
      "command": "npx",
      "args": ["-y", "@glesumdev/anvilbase-mcp"],
      "env": { "ANVILBASE_URL": "https://your-host" }
      // GUI-launched: add "ANVILBASE_TOKEN": "anvilbase_pat_…" here
    }
  }
}

Zed restarts the server on save; tools appear in the Agent Panel.

Warp

anvilbase mcp setup --agent warp writes ./.warp/.mcp.json (or --global). Or paste the { "mcpServers": { … } } block via ⌘P → MCP servers → + Add.

Private package & local build

@glesumdev/anvilbase-mcp is published privately (npm, restricted), so npx -y @glesumdev/anvilbase-mcp needs npm auth to the glesumdev org (npm login, or a token in ~/.npmrc). When developing the server itself, skip npm and point your tool at the local build (no build step — bun runs the TypeScript directly):

"command": "bun",
"args": ["run", "/ABSOLUTE/PATH/TO/anvilbase/packages/mcp/src/index.ts"],

The repo’s checked-in .mcp.json already uses the local build, so inside the repo Claude Code picks it up automatically.

Troubleshooting

• 401 / “ANVILBASE_TOKEN unset” — the token isn’t reaching the server. Export it in the launching shell, or add it to the env block (GUI apps).
• Server won’t start — for the npx form, make sure you’re npm-authenticated to the private glesumdev org (npm whoami) and that Node or bun is on PATH. For local hacking, use the bun run … local-build form.
• Check status — anvilbase mcp status shows configured tools and whether the token resolves.
• Undo — anvilbase mcp remove --agent zed,warp,claude-code (match the scope you set up; originals are restored from *.anvilbase.bak).

Safety

The MCP server acts with your management token — i.e. deployment-admin power. Use a scoped PAT, point AI tools at a dev/staging deployment for exploratory work, and avoid wiring an assistant directly to production with a service-role key unless you intend it.

Next: SDK Compatibility.