# MCP

Connect Claude, Cursor, or any MCP-compatible client to your workspace. The hosted endpoint at `mcp.zerobuild.ai` is the fastest way in — no install, nothing to run.

## Connect with OAuth (recommended)

In Claude (Settings → Connectors → **Add custom connector**), paste:

```
https://mcp.zerobuild.ai
```

The client registers itself via OAuth 2.1 with Dynamic Client Registration, walks you through Zerobuild's consent screen, and gets a workspace-scoped token — no API key to copy. Revoke access any time in **Settings → Connected Apps**. The same flow works in any client that follows the MCP authorization spec.

## Connect with an API key

For autonomous agents, CI, and scripts: create a key in **Settings → API Keys** and authenticate with `Authorization: Bearer zb_live_...` against the same endpoint. Clients that only speak stdio (Claude Desktop's stable channel) can spawn the `@zerobuild/mcp` npm package, which forwards to the hosted endpoint.

## What an agent can do

Tools are gated by the scope you grant — `read`, `write`, or `admin`:

- **read** — `search` (the same unified search your team uses), `list_conversations`, `list_channels`, `get_document_as_markdown`, `list_sites`, plus read-only resources: channels, conversations, contacts, documents and their versions, and the workspace's published docs.
- **write** — everything above, plus acting: `reply_to_conversation`, `add_internal_note`, `close_conversation`, `assign_conversation`, `transfer_conversation`, `tag_conversation`, `send_message`, `create_document`, `update_document` — and shaping the [Library](/library): `create_folder`, `move_document`, `reorder_document`, `reorder_folder`, `set_document_slug`, `set_document_visibility`.
- **admin** — everything above, plus [help-center](/help-center) site management: `create_site`, `update_site`, `publish_site`, `unpublish_site`.

An agent connected with `read` can research; with `write` it can work — draft replies, leave notes for the team, file documents, and organize an entire help center's structure (folders become nav sections, slugs become URLs); with `admin` it can take a site live. Documents go in and come out as markdown, and `create_document` can set the article's slug and draft/published state in the same call.

## Version pinning

The contract is date-versioned. The bare URL tracks latest; append a version date (`https://mcp.zerobuild.ai/{version}`) to freeze your client against that tool shape. Deprecated versions keep working for 12 months after a successor ships, with an `X-API-Deprecation` warning header from month 6.