# Connect to the Duvo MCP server

Duvo exposes a hosted MCP server at `https://api.duvo.ai/v1/mcp`. Connect to it from any MCP-compatible host — Claude Desktop, Cursor, ChatGPT connectors, your own client — and every Duvo [Public API](https://github.com/duvoai/monorepo/blob/gitbook-prod/knowledge-base/api-reference/README.md) endpoint becomes a tool the host can call.

Use this to:

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

## What you can do

Every endpoint registered in the [Public API](https://github.com/duvoai/monorepo/blob/gitbook-prod/knowledge-base/api-reference/README.md) is auto-exposed as an MCP tool. That includes:

* **Assignments** — list, get, create, update
* **Jobs (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
* **Skills, Plugins, Sandboxes** — list and reference

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/v1/mcp
```

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

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

1. Add `https://api.duvo.ai/v1/mcp` as the MCP server URL in your host's settings.
2. The host detects the OAuth challenge and opens a browser tab to Duvo's sign-in page.
3. Sign in and approve the connection.
4. The host stores the OAuth tokens and uses them automatically on every tool call.

Duvo's MCP server publishes its OAuth metadata at `https://api.duvo.ai/.well-known/oauth-protected-resource/v1/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).

1. Generate a key in the Duvo dashboard at [Team Settings → API Keys](https://app.duvo.ai/settings/api-keys).
2. Configure the MCP host to send the key as a bearer token in the `Authorization` header:

   ```
   Authorization: Bearer <your-api-key>
   ```
3. The host can then call Duvo MCP tools without any further sign-in.

API keys are scoped to a team 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:

### Claude Desktop

Edit your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "duvo": {
      "url": "https://api.duvo.ai/v1/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.

### Cursor

In Cursor settings, open the MCP servers section, add a new server with the URL `https://api.duvo.ai/v1/mcp`, and let Cursor run the OAuth flow.

### ChatGPT (Custom Connector)

Add a Custom Connector pointing to `https://api.duvo.ai/v1/mcp`. ChatGPT handles Dynamic Client Registration and the OAuth flow automatically.

### Custom MCP host or script

Any MCP-compatible client library (TypeScript, Python, etc.) can connect — point it at `https://api.duvo.ai/v1/mcp`, supply either an OAuth token or an API key, and call `tools/list` to discover what's available.

## Tool ergonomics

Tools follow the underlying Public API:

* Tool names map to OpenAPI `operationId`s (for example, `list_agents`, `start_run`, `get_connection`).
* 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](https://github.com/duvoai/monorepo/blob/gitbook-prod/knowledge-base/api-reference/README.md) for the exact shapes.

## 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 Jobs are not streamed over MCP today — start the Job via the tool, then poll `get_run` or `list_run_messages` to monitor progress.

## Troubleshooting

* **401 Unauthorized** — Your token is missing, expired, or for a different audience. Re-run OAuth, or regenerate the API key in the dashboard.
* **403 Forbidden** — Your account doesn't have permission to call this endpoint. Check your team role and Connection permissions.
* **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.

## Related

* [Custom MCP Connections](/mcp/custom-mcp-servers.md) — the other direction: bring your own MCP server into Duvo
* [Public API Reference](https://github.com/duvoai/monorepo/blob/gitbook-prod/knowledge-base/api-reference/README.md) — the API the Duvo MCP server wraps
* [Duvo CLI](https://github.com/duvoai/monorepo/blob/gitbook-prod/knowledge-base/cli/README.md) — terminal-first wrapper over the same API


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.duvo.ai/mcp/duvo-mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.