Skip to main content

MCP server reference

This page is the developer-facing contract for Zoie's MCP server. For the end-user "connect my assistant" guide, see the MCP section.

Endpoint​

The server is reached at the bare origin — no path, no trailing slash:

https://mcp.zoie.ai        # production
https://beta-mcp.zoie.ai   # beta
https://dev-mcp.zoie.ai    # dev

The streamable-HTTP transport is served at /, and the protected-resource metadata advertises resource as the origin itself — so clients connect to the origin directly, with no /mcp suffix.

Transport​

Zoie implements the Streamable HTTP MCP transport. Use any MCP client/SDK that supports it (the official SDKs do). After authorizing, the client performs the standard MCP handshake and can call tools/list and tools/call.

Authentication​

Authorization is OAuth 2.1 with Dynamic Client Registration (DCR) — clients register themselves; there are no pre-shared API keys.

Discovery follows the standards, so a compliant client needs only the endpoint:

  1. The client requests the protected resource metadata (RFC 9728) from the origin, which names the authorization server.
  2. The client fetches the authorization server metadata (RFC 8414) and registers via DCR (RFC 7591).
  3. The user completes the authorization-code flow (with PKCE) on Zoie's consent screen, selecting a business and approving scopes.
  4. The client receives a token scoped to that business and those scopes, and uses it as a bearer token on MCP requests.

Tokens can be revoked by the user at any time from Zoie (Settings → Claude / ChatGPT / Other MCP connectors), which immediately invalidates the client's access.

Scopes​

Access is requested per category, split into read and write:

ScopeGrants
leads:read / leads:writeRead / create & update leads and contacts
conversations:read / conversations:writeRead / act on messages and call logs
appointments:read / appointments:writeRead / book & manage appointments
campaigns:read / campaigns:writeRead / act on campaigns and pipeline

Request the least your client needs. The user can decline individual scopes at consent; your client should handle a narrower grant than requested.

Business scoping​

Every token is bound to a single business. To operate across multiple businesses, obtain a separate authorization (and token) per business. There is no cross-business access within one grant.

Tools​

Discover the available tools at runtime with tools/list — don't hard-code the catalogue, as it evolves. Tools span these categories (the same ones surfaced in the in-app activity log):

  • Leads — query, create, and update leads/contacts
  • Messages — read conversation history and messages
  • Emails — read email threads
  • Appointments — read availability, book, reschedule
  • Campaigns — read campaign/pipeline performance
  • Notes — add notes to records
  • Search — search across the workspace
  • Other — account/utility tools (e.g. listing the businesses you can access)

Each tool call is recorded against the grant (tool name, summary, status) and surfaced to the user in the connection's activity log, so design your client to make purposeful, auditable calls.

Building a client — checklist​

  • Use an MCP SDK with streamable HTTP support.
  • Point it at the correct origin for the target environment.
  • Let DCR + the RFC 9728/8414 discovery handle registration and the auth-server lookup — only the endpoint URL is required up front.
  • Request minimal scopes; degrade gracefully if some are declined.
  • Treat each token as one business.
  • Call tools/list to discover capabilities; handle tool errors returned in the MCP response.
Expanding

A worked example client and the full tool schemas will be added here.