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

# Connect to the Duvo MCP server

> Connect Claude Desktop, Cursor, or ChatGPT to the Duvo MCP server. Every Public API endpoint becomes an LLM-callable tool.

Connecting an MCP host to the Duvo MCP server is the main way teams use MCP with Duvo — it's the conversational counterpart to the [Duvo CLI](/cli).

Duvo exposes a hosted MCP server at `https://api.duvo.ai/v2/mcp`. Connect to it from any MCP-compatible host — Claude Desktop, Cursor, ChatGPT connectors, your own client — and every Duvo [Public API](../api-reference) endpoint becomes a tool the host can call.

Use this to:

* Drive Duvo Agents from an AI assistant chat ("Start the invoice processor on yesterday's batch and tell me when it's done.")
* Inspect Runs, Cases, and Files conversationally
* Build hybrid workflows where one assistant orchestrates Duvo Agents alongside other tools

## What you can do

Every endpoint registered in the [Public API](../api-reference) is auto-exposed as an MCP tool. That includes:

* **Agents** — list, get, create, update
* **Runs** — start, get status, send messages, respond to human-in-the-loop requests, stop
* **Connections** — list and inspect your authorized accounts
* **Files** — list, read, write, rename, delete
* **Cases and Queues** — inspect, delegate, label
* **Clarity** — create a process, invite people to interviews, see who has done theirs, and read the process summaries
* **Skills, Plugins, Sandboxes** — list and reference

See the full list of available tools on the [Available MCP Tools](/mcp/available-tools) page.

When Duvo ships a new Public API endpoint, it automatically becomes an MCP tool on the next deploy. There's no separate maintenance step.

## Server URL

```
https://api.duvo.ai/v2/mcp
```

The server uses MCP's **Streamable HTTP** transport (`POST /v2/mcp`). Most modern MCP hosts support this transport out of the box.

<Note>
  The earlier `https://api.duvo.ai/v1/mcp` endpoint still works and serves the
  same tools as `/v2/mcp`, so existing setups keep running unchanged — including
  after the `/v1` API sunset. New connections should use `/v2/mcp`.
</Note>

## Authentication

The Duvo MCP server accepts two credential types:

### Option 1 — OAuth (recommended for personal use)

Recommended for hosts that prompt you to sign in (Claude Desktop, Cursor, ChatGPT connectors). The host runs a one-time browser-based sign-in to Duvo, then handles token refresh and revocation for you. No API key to copy or rotate.

The exact steps depend on the host. In general:

<Steps>
  <Step title="Add the server URL" icon="link">
    Add `https://api.duvo.ai/v2/mcp` as the MCP server URL in your host's settings.
  </Step>

  <Step title="Trigger the OAuth challenge" icon="app-window">
    The host detects the OAuth challenge and opens a browser tab to Duvo's sign-in page.
  </Step>

  <Step title="Sign in and approve" icon="circle-check">
    Sign in and approve the connection.
  </Step>

  <Step title="Tokens stored automatically" icon="lock">
    The host stores the OAuth tokens and uses them automatically on every tool call.
  </Step>
</Steps>

Duvo's MCP server publishes its OAuth metadata at `https://api.duvo.ai/.well-known/oauth-protected-resource/v2/mcp` (RFC 9728). Compliant MCP hosts use this to discover the authorization server and register themselves via [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) automatically.

### Option 2 — API key (recommended for scripts and service accounts)

Use API keys when the host doesn't support OAuth, or for non-interactive use (CI, service accounts).

<Steps>
  <Step title="Generate an API key" icon="key">
    Generate a key in the Duvo dashboard at [Your Profile → API keys](https://app.duvo.ai/settings/profile#api-keys), scoped to a single team or to all teams you can access. Users with the Manager role or above can also create a team's keys at [Team Settings → API keys](https://app.duvo.ai/settings/api-keys).
  </Step>

  <Step title="Send the key as a bearer token" icon="code">
    Configure the MCP host to send the key as a bearer token in the `Authorization` header:

    ```
    Authorization: Bearer <your-api-key>
    ```
  </Step>

  <Step title="Call tools" icon="play">
    The host can then call Duvo MCP tools without any further sign-in.
  </Step>
</Steps>

API keys are scoped to a single team or to all teams the owner can access, and inherit the permissions of the user who generated them.

## Setup by host

The MCP standard means the same Duvo URL works in every compliant host. Configuration syntax differs slightly between products, so check your host's MCP setup guide for the exact field names. Common patterns:

<Tabs>
  <Tab title="Claude Desktop">
    Edit your Claude Desktop config (`claude_desktop_config.json`):

    ```json theme={"dark"}
    {
      "mcpServers": {
        "duvo": {
          "url": "https://api.duvo.ai/v2/mcp"
        }
      }
    }
    ```

    Restart Claude Desktop. When you mention Duvo or use a tool from the connector, Claude Desktop opens a browser tab for OAuth sign-in.
  </Tab>

  <Tab title="Claude Code">
    Add the Duvo server from your terminal with the `claude mcp add` command:

    ```bash theme={"dark"}
    claude mcp add --transport http duvo https://api.duvo.ai/v2/mcp
    ```

    The first time you call a Duvo tool, Claude Code runs the browser-based OAuth sign-in. To use an API key instead (for CI or service accounts), pass it as a bearer header:

    ```bash theme={"dark"}
    claude mcp add --transport http duvo https://api.duvo.ai/v2/mcp \
      --header "Authorization: Bearer <your-api-key>"
    ```
  </Tab>

  <Tab title="Cursor">
    In Cursor settings, open the MCP servers section, add a new server with the URL `https://api.duvo.ai/v2/mcp`, and let Cursor run the OAuth flow.
  </Tab>

  <Tab title="ChatGPT (Custom Connector)">
    Add a Custom Connector pointing to `https://api.duvo.ai/v2/mcp`. ChatGPT handles Dynamic Client Registration and the OAuth flow automatically.
  </Tab>

  <Tab title="Custom MCP host or script">
    Any MCP-compatible client library (TypeScript, Python, etc.) can connect — point it at `https://api.duvo.ai/v2/mcp`, supply either an OAuth token or an API key, and call `tools/list` to discover what's available.
  </Tab>
</Tabs>

## Tool ergonomics

Tools follow the underlying Public API:

* Tool names map to OpenAPI `operationId`s (for example, `listAgents`, `startRun`, `getConnection`).
* Tool descriptions come from each endpoint's OpenAPI description.
* Input schemas are flat — path parameters, query parameters, and request body are merged into a single object so calls read naturally (`startRun({ agent_id: "...", input: "..." })` rather than wrapping each section).
* Responses match the corresponding API response. Use the [Public API Reference](../api-reference) for the exact shapes.
* Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so hosts can tell a read from a write and know which tools reach outside Duvo — for example `startRun`, `probeMcpServer`, or the OAuth start tools.
* Not-found errors name the id parameter that failed and echo the value you sent (for example `case_queue_id`), so a call that takes several ids tells you which one to check.

## Built-in skills

The server also ships Duvo's [Agent Skills](https://github.com/duvoai/skills) as MCP resources, so your host has the same guidance without installing anything. Each skill is a markdown file under `duvo://skills/`:

| Resource | Use it to |
| - | - |
| `duvo://skills/aop-writer/SKILL.md` | Draft, rewrite, or critique an Agent's AOP |
| `duvo://skills/run-debugger/SKILL.md` | Find out why a Run failed or produced the wrong outcome |
| `duvo://skills/workflow-debugger/SKILL.md` | Audit an Agent or a Queue-connected workflow across many Runs |
| `duvo://skills/improve-agent/SKILL.md` | Take one Agent from where it is to an applied improvement |
| `duvo://skills/improve-queue/SKILL.md` | Do the same for a Queue and the producer/consumer workflow around it |
| `duvo://skills/connection-doctor/SKILL.md` | Diagnose the Connections and Logins an Agent relies on |
| `duvo://skills/clarity-mapping/SKILL.md` | Map how a process works with Clarity, from interviews to analysis |

The server's instructions tell the host when to read each skill, and reference files sit next to each `SKILL.md` under `references/`. Hosts that surface MCP resources (Claude Desktop, Claude Code, Cursor) list them automatically.

<Note>
  The skills are the same content as the public `duvoai/skills` repository,
  which you can still install locally to use with the [Duvo CLI](/cli).
</Note>

## Limits and behavior

* All Public API rate limits apply to MCP tool calls.
* Every tool call respects the permissions of the authenticating user, just like a direct API call.
* Long-running Runs are not streamed over MCP today — start the Run via the tool, then poll `getRun` or `listRunMessages` to monitor progress.

## Troubleshooting

<Warning>
  **401 Unauthorized** — Your token is missing, expired, or for a different audience. Re-run OAuth, or regenerate the API key in the dashboard.
</Warning>

<Warning>
  **403 Forbidden** — Your account doesn't have permission to call this endpoint. Check your team role and Connection permissions.
</Warning>

<Warning>
  **OAuth doesn't open a browser** — The host may not support Dynamic Client Registration. Fall back to API key authentication, or check the host's docs for OAuth setup steps.
</Warning>

## Privacy and terms

* [Privacy Policy](https://www.duvo.ai/privacy-policy) — how Duvo handles data accessed through the MCP server.
* [Terms of Use](https://www.duvo.ai/terms-of-use) — the terms that apply to Duvo API and MCP usage.

For platform-wide details (SOC 2 certification, encryption, Anthropic Zero Data Retention, sub-processors), see [Security & Privacy](/user-guide/resources/security-and-privacy).

## Related

<CardGroup cols={2}>
  <Card title="Available MCP Tools" icon="wrench" href="/mcp/available-tools">
    The full catalog of tools this server exposes.
  </Card>

  <Card title="Connect a custom MCP to Duvo" icon="link" href="/mcp/custom-mcp-servers">
    The other direction: bring your own MCP server into Duvo.
  </Card>

  <Card title="Public API Reference" icon="code" href="../api-reference">
    The API the Duvo MCP server wraps.
  </Card>

  <Card title="Duvo CLI" icon="terminal" href="/cli">
    Terminal-first wrapper over the same API.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.