> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP quickstart

> Connect an MCP client to Darwin Search and Act.

Connect a compatible AI client to Darwin's canonical remote MCP server. The client receives focused tools through user-scoped OAuth—never your Darwin password or a pasted API key.

```text theme={null}
https://mcp.darwin.so/mcp
```

<Steps>
  <Step title="Add the remote server">
    ## Add the remote server

    Open your client's MCP settings and add the endpoint above as a **remote HTTP server**. Name it `Darwin` if the client asks for a display name.

    <Note>Client menus change frequently. The server URL and Darwin tool contract do not.</Note>
  </Step>

  <Step title="Sign in and choose scopes">
    ## Sign in and choose scopes

    Complete Darwin sign-in in the browser. Approve only the scopes the client needs:

    | Scope            | Purpose                                             |
    | ---------------- | --------------------------------------------------- |
    | `directory:read` | Search public executable capabilities.              |
    | `agent:write`    | Start, read, update, approve, or stop your Actions. |

    OAuth access is user-scoped and revocable. Provider connections and payment approvals remain separate from MCP authorization.
  </Step>

  <Step title="Verify the tool list">
    ## Verify the tool list

    A full connection advertises one read-only Search tool and six focused Action tools.

    | Tool             | Use it to                                       |
    | ---------------- | ----------------------------------------------- |
    | `search`         | Find and rank public executable capabilities.   |
    | `start_action`   | Start work from an exact capability revision.   |
    | `get_action`     | Read the truthful current state.                |
    | `list_actions`   | Recover current nonterminal work.               |
    | `update_action`  | Supply requested information without approving. |
    | `approve_action` | Approve or reject an exact reviewed decision.   |
    | `stop_action`    | Stop work when the current state allows it.     |

    If the client shows a different tool set, reconnect before relying on it.
  </Step>

  <Step title="Try Search, then Act">
    ## Try Search, then Act

    Ask:

    > Search Darwin for OCR that supports handwriting and tables. Show me the provider, capability, match evidence, availability, and pricing before doing anything.

    After you select a result, ask:

    > Use that exact capability and revision to process this document. Keep the Action ID and stop if Darwin needs information, connection, payment, or approval.
  </Step>
</Steps>

## Handle pauses correctly

A successful tool call can return nonterminal work. The client should render `status`, `actionRequired`, `availableActions`, and any first-party `webLink` exactly as returned.

| Darwin state          | Client behavior                                                               |
| --------------------- | ----------------------------------------------------------------------------- |
| `awaiting_user`       | Ask for the missing information, then call `update_action`.                   |
| `connection_required` | Open the first-party link after a user gesture; keep reading the same Action. |
| `payment_required`    | Show the bound terms and first-party link; never infer payment success.       |
| `approval_required`   | Show the exact reviewed payload and decision choices.                         |
| `running`             | Poll `get_action` with bounded backoff.                                       |

<Warning>Closing a browser window, finishing an assistant response, or receiving HTTP 200 is not proof that external work completed.</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client cannot discover Darwin tools">
    Confirm the endpoint is exactly `https://mcp.darwin.so/mcp`, remove stale duplicate entries, then reconnect and complete OAuth again.
  </Accordion>

  <Accordion title="Search works but Action tools fail">
    The connection may only have `directory:read`. Reauthorize with `agent:write` for Action reads and mutations.
  </Accordion>

  <Accordion title="A task was interrupted">
    Use `list_actions` or a stored `actionId`, then call `get_action`. Do not create replacement work until you know the existing Action state.
  </Accordion>
</AccordionGroup>