@zerobuild/mcp

MCP (Model Context Protocol) server for Zerobuild. Connect Claude Desktop, Cursor, Continue, or any MCP-compatible AI agent to your Zerobuild workspace.

For most users, the easiest path is the hosted endpoint at https://mcp.zerobuild.ai — no install, no Node, no PATH issues. This npm package is for self-hosters, on-prem deployments, and local development. See the docs for hosted setup.

When to use this package

• Self-hosting the Zerobuild stack (you run your own app.your-domain.com and want MCP on your own infrastructure).
• Local development against a dev server.
• Air-gapped / on-prem deployments where the agent and the Zerobuild instance live behind the same firewall.
• Any case where you'd prefer stdio over a remote HTTP connection.

If none of those apply, point your MCP client at https://mcp.zerobuild.ai with a bearer API key — that's it.

Quick Start (stdio)

1. Create an API Key

In your Zerobuild workspace, go to Settings → API Keys and create a key with read,write scopes (or read for read-only access).

2. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zerobuild": {
      "command": "npx",
      "args": ["-y", "@zerobuild/mcp"],
      "env": {
        "ZEROBUILD_API_KEY": "zb_live_...",
        "ZEROBUILD_URL": "https://app.zerobuild.ai"
      }
    }
  }
}

Claude Code:

claude mcp add zerobuild -- npx -y @zerobuild/mcp
# Then set env vars: ZEROBUILD_API_KEY, ZEROBUILD_URL

Cursor — add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Cursor accepts both the hosted HTTP form and the stdio form, so pick whichever you prefer:

// HTTP — no install, no Node
{
  "mcpServers": {
    "zerobuild": {
      "url": "https://mcp.zerobuild.ai",
      "headers": {
        "Authorization": "Bearer zb_live_..."
      }
    }
  }
}

// Stdio with inline env values
{
  "mcpServers": {
    "zerobuild": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zerobuild/mcp"],
      "env": {
        "ZEROBUILD_API_KEY": "zb_live_...",
        "ZEROBUILD_URL": "https://app.zerobuild.ai"
      }
    }
  }
}

// Stdio with .env file
{
  "mcpServers": {
    "zerobuild": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zerobuild/mcp"],
      "envFile": ".env"
    }
  }
}

# .env (next to .cursor/mcp.json)
ZEROBUILD_API_KEY=zb_live_...
ZEROBUILD_URL=https://app.zerobuild.ai

Cursor gotcha: don't combine "envFile" with "env": { ... "${env:ZEROBUILD_API_KEY}" }. Cursor's ${env:VAR} expansion reads from Cursor's own process environment, not from envFile — the value silently expands to an empty string and every API call 401s. Pick one shape, not both.

Continue — add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "zerobuild",
      "transport": {
        "type": "streamable-http",
        "url": "https://mcp.zerobuild.ai",
        "headers": {
          "Authorization": "Bearer zb_live_..."
        }
      }
    }
  ]
}

3. HTTP mode (single-tenant self-host)

Run as a local HTTP endpoint instead of stdio:

ZEROBUILD_API_KEY=zb_live_... \
ZEROBUILD_URL=https://app.zerobuild.ai \
npx -y @zerobuild/mcp --http

Server starts at http://localhost:3002/mcp (configurable via MCP_PORT). Any MCP client that supports the Streamable HTTP transport can connect.

Note: this is single-tenant — one API key per server. The hosted endpoint at https://mcp.zerobuild.ai is multi-tenant (per-request bearer auth) and is the recommended path for most setups.

API version pinning

Each Zerobuild API contract is identified by a date. Pin a specific version to freeze your client against a known tool/resource shape, so future contract changes don't break your workflows mid-stream:

ZEROBUILD_API_VERSION=2026-04-09 npx -y @zerobuild/mcp

Without the env var, the package uses its built-in pinned date (which advances with each release). The X-API-Version header is forwarded on every REST call to the Zerobuild API; the date you pin determines which contract shape the API responds with.

What's Available

Resources (read context)

| Resource | Description | |---|---| | zerobuild://conversations | Open live chat conversations | | zerobuild://conversations/{id} | Conversation detail with messages | | zerobuild://contacts | All contacts | | zerobuild://contacts/{id} | Contact detail | | zerobuild://channels | Team chat channels | | zerobuild://channels/{id}/messages | Recent channel messages | | zerobuild://documents | Document tree | | zerobuild://documents/{id} | Document content | | zerobuild://search/{query} | Unified search | | zerobuild://versions | Available API contract versions + your pin |

Tools (actions)

Each tool requires a specific scope — keys created with read can only call read tools; write covers everything except future admin-only tools.

| Tool | Scope | Description | |---|---|---| | search | read | Full-text search | | list_channels | read | List channels with IDs | | list_conversations | read | List conversations with IDs | | send_message | write | Send message to a channel | | reply_to_conversation | write | Reply to a customer | | add_internal_note | write | Add internal note (team only) | | close_conversation | write | Close a conversation | | assign_conversation | write | Assign to an agent | | transfer_conversation | write | Transfer with handoff note | | tag_conversation | write | Add/remove tags | | create_document | write | Create doc or folder | | update_document | write | Update doc content |

A tool call with insufficient scope returns an INSUFFICIENT_SCOPE tool result with isError: true — the agent can recover and prompt for an upgraded key without the session terminating.

Prompts (workflows)

| Prompt | Description | |---|---| | summarize-conversation | Summarize with customer context | | draft-reply | Draft reply using conversation history | | find-related | Find related conversations/docs | | conversation-handoff | Generate transfer summary | | daily-digest | Daily conversation activity digest |

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | ZEROBUILD_API_KEY | Yes | — | API key (zb_live_*) | | ZEROBUILD_URL | No | https://app.zerobuild.ai | Zerobuild API base URL | | ZEROBUILD_API_VERSION | No | (package-pinned date) | Pin a specific API contract version | | MCP_PORT | No | 3002 | HTTP server port (--http mode only) |

Examples

Ask Claude to summarize today's conversations:

"Summarize all open live chat conversations in my Zerobuild workspace"

Create a doc from a conversation:

"Take the key points from conversation #42 and create a document called 'Meeting Follow-up'"

Reply to a customer:

"Draft a reply to the latest message in conversation #15, suggesting they check our docs"

Search across everything:

"Search my workspace for anything related to 'shipping delay'"