# 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:

```text
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](/docs/agent-access/create-and-manage-tokens.md) for the web setup. Before promising ChatGPT or Claude compatibility, read [Connect ChatGPT, Claude, or another MCP client](/docs/agent-access/chatgpt-claude-compatibility.md); the client must securely support Domino's bearer header.

Example client configuration shape:

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

```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;
- 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, capture, planning, RSVP, availability, and commit sequences.