Domino MCP guide

Domino MCP exposes authorized, registry-generated social-planning tools. The MCP client's model interprets the user's request; Domino validates and executes typed capabilities without invoking another model inside the tool call.

Endpoint and authentication

The MCP endpoint is:

POST https://letsdomino.io/mcp/v2

Use an agent-access bearer token created in Domino's Agent Access settings. Choose only the abilities the client needs:

• planning:read — inspect and search;
• planning:write — create and change private Domino state;
• planning:rsvp — respond to invitations;
• planning:commit — commit an eligible prepared external action.

Do not paste the token into an ordinary conversation or documentation prompt.

Use Create, test, rotate, and revoke Agent Access tokens for the web setup. Before promising ChatGPT or Claude compatibility, read Connect ChatGPT, Claude, or another MCP client; the client must securely support Domino's bearer header.

Example client configuration shape:

{
  "mcpServers": {
    "domino": {
      "url": "https://letsdomino.io/mcp/v2",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Agent-Client": "your-client-name"
      }
    }
  }
}

Use the configuration format required by the actual MCP client.

Protocol methods

Domino supports:

• initialize;
• tools/list;
• tools/call;
• standard client notifications, which receive no response.

Tool discovery is authorization-filtered. A token should not see tools for abilities it does not have. Consequential capabilities are not exposed directly; actions.commit is the only external-effect tool exposed when commit authority is available.

Tool calls

Call the exact tool returned by tools/list. For writes, include a stable caller-generated idempotency_key in the tool arguments. Domino removes that transport field before validating the capability input.

Example JSON-RPC shape:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "TOOL_FROM_TOOLS_LIST",
    "arguments": {
      "idempotency_key": "stable-intent-key-001"
    }
  }
}

Fetch the current MCP tool catalog for schemas, but treat tools/list from the authenticated connection as authoritative for that principal.

Results

Each successful tool call contains:

• content — safe conversational fallback text;
• structuredContent — the canonical typed Domino outcome;
• isError — whether the capability failed.

Use structuredContent for state and control flow. Use fallback text for conversational presentation when the client cannot render the structure. Do not expose raw handles, execution IDs, tokens, or JSON unless the user asks for debugging output.

References and collections

Use Domino-issued opaque handles, snapshot handles, and cursors returned in typed outcomes. Do not retain or invent internal database IDs.

For a collection:

• select against the returned snapshot;
• use next_cursor for more items;
• do not rerun discovery merely to reconstruct ordinal choices;
• refresh only when the user changes the underlying constraints or requests fresh state.

Prepared external actions

The safe pattern is:

1. Call the appropriate draft or prepare tool.
2. Present the exact prepared action and required disclosures to the user.
3. Stop.
4. Obtain a later explicit user approval.
5. Call actions.commit with the prepared action handle and a stable idempotency key from the same authenticated MCP principal.
6. Present only the confirmed returned effect.

Never ask an MCP user to reply with the SMS-only SEND protocol.

Error recovery

• needs_input: obtain the requested user information and make an intentional follow-up call.
• accepted: use the returned polling or status action.
• execution_in_progress: retain the execution reference and poll rather than creating a new mutation.
• idempotency_conflict: do not alter input under the old key; use a new key for an intentionally changed request.
• reference_unavailable: rediscover an authorized current reference.
• prepared action expired or superseded: prepare again and obtain new approval.

LLM answering guidance

• Read before mutating when a named object may already exist.
• Preserve the user's constraints in typed input; never place free prose into a handle field.
• Treat returned confirmed effects as the only authority for claims about mutations or sends.
• Use MCP task recipes and continuation patterns for end-to-end people, list, capture, planning, RSVP, availability, and commit sequences.