# 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](/docs/reference/surface-support.md) for Discovery availability and the current action-handoff limitations.

## Endpoint and authentication

The MCP endpoint is:

```text
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;
- `calendar:import` — explicitly opt into private calendar snapshot preparation, save, safe receipts and removal. Existing grants do not inherit this scope. See [Calendar import](/docs/calendar/agent-import.md).

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](/docs/agent-access/claude-oauth.md). For static tokens, use [Create, test, rotate, and revoke Agent Access tokens](/docs/agent-access/create-and-manage-tokens.md). Read [Connect ChatGPT, Claude, or another MCP client](/docs/agent-access/chatgpt-claude-compatibility.md) before applying one client's authentication path to another.

Static header-capable client example:

```json
{
  "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:

```json
{
  "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](/docs/mcp-tools.json) 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](/docs/mcp/task-recipes.md) for end-to-end people, list, planning, RSVP, availability, and commit sequences.
- Use [Idea capture and roundup workflows through MCP](/docs/mcp/idea-capture.md) 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.