Domino MCP guide

Domino MCP exposes authorized, registry-generated social-planning tools. The host assistant owns conversational interpretation and tool selection; Domino validates and executes typed capabilities without taking over the conversation. Individual capabilities, such as capture or idea generation, may still perform their own model work.

For external Discovery, the host assistant performs the research. Domino's prepare/record tools supply context and retain the submitted results without invoking Domino's research model or independently fetching sources to verify the host's claims. See Feature support by surface for Discovery availability and the current action-handoff limitations.

Endpoint and authentication

The MCP endpoint is:

POST https://letsdomino.io/mcp

Every request must carry a bearer token. Domino supports two ways to obtain one:

• claude.ai hosted custom connectors use Domino's browser OAuth flow;
• Claude Code, Capability API clients, and other header-capable clients can use a static 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 any access or refresh token into an ordinary conversation or documentation prompt.

For claude.ai, use Connect claude.ai to Domino with OAuth. For static tokens, use Create, test, rotate, and revoke Agent Access tokens. Read Connect ChatGPT, Claude, or another MCP client before applying one client's authentication path to another.

Static header-capable client example:

{
  "mcpServers": {
    "domino": {
      "url": "https://letsdomino.io/mcp",
      "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;
• when the user asks for all results, continue with the returned snapshot_handle and next_cursor until has_more is false;
• never present a page's returned count as the total collection count;
• 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, planning, RSVP, availability, and commit sequences.
• Use Idea capture and roundup workflows through MCP for singular capture, clarification, polling, media boundaries, and multi-step roundup state.

Retained research to Save and private Plan

Check the authenticated tools/list response. When available, domino_save_discovery_results projects the shared Save capability; it does not start research. Schema availability does not enable Discovery for an account or authorize an action without a user request.

1. Use the existing domino_prepare_discovery → host research → domino_record_discovery_results flow. Submitted claims remain host_researched and unverified; Domino does not fetch their URLs or invoke its research model during this handoff.
2. Inspect the record result's structuredContent.outcome.facts.choices when selection_contract is domino.discovery-selection.v1. After an explicit Save request, copy the selected actions.save.input into domino_save_discovery_results arguments and add a stable idempotency_key. Several selections must share one envelope and use exactly their returned snapshot refs. Do not derive a selection from a venue name or corpus handle.
3. After an explicit Plan request, copy actions.plan.input into domino_draft_invite arguments with its own stable key. Direct result entry includes the complete research_selection; saved-list entry uses the returned candidate and list handles. This creates or reopens a private draft only.
4. Read Save's outcome.facts.readback and Plan's returned plans.status.get next action through their matching registry tools. Owner list items and Plan status preserve the exact research source, evidence, original requirements and actual scheduling state. An exact write retry replays its receipt even after selection expiry; an authorized saved-item Plan entry remains durable.

If the tool, action template or required authority is unavailable, explain that boundary and use the returned Web link. Do not invoke server research, silently drop blocked results or claim that a private draft was sent. These interfaces do not establish acceptance by every MCP host or a complete live conversational journey.