Duvo

Servidor MCP hospedado para Duvo — inicie execuções, inspecione aprovações e exponha ferramentas de execução de supermercado/varejo a agentes compatíveis.

Ver em duvo.aiExperimente este MCPPatrocinado

Documentação

Conecte-se ao servidor MCP da Duvo

Conecte o Claude Desktop, Cursor ou ChatGPT ao servidor MCP da Duvo. Cada endpoint da Public API se torna uma ferramenta chamável por LLM.

Conectar um host MCP ao servidor MCP da Duvo é a principal forma de as equipes usarem MCP com a Duvo — é a contraparte conversacional da CLI da Duvo.

A Duvo disponibiliza um servidor MCP hospedado em https://api.duvo.ai/v2/mcp. Conecte-se a ele a partir de qualquer host compatível com MCP — Claude Desktop, Cursor, conectores do ChatGPT, seu próprio cliente — e cada endpoint da Public API da Duvo se torna uma ferramenta que o host pode chamar.

Use isso para:

Acionar Agentes da Duvo a partir de um chat com assistente de IA ("Inicie o processador de faturas no lote de ontem e me avise quando terminar.")
Inspecionar Runs, Cases e Files de forma conversacional
Construir fluxos de trabalho híbridos em que um assistente orquestra Agentes da Duvo junto com outras ferramentas

O que você pode fazer

Cada endpoint registrado na Public API é exposto automaticamente como uma ferramenta MCP. Isso inclui:

Agents — listar, obter, criar, atualizar
Runs — iniciar, obter status, enviar mensagens, responder a solicitações human-in-the-loop, parar
Connections — listar e inspecionar suas contas autorizadas
Files — listar, ler, escrever, renomear, excluir
Cases e Queues — inspecionar, delegar, rotular
Skills, Plugins, Sandboxes — listar e referenciar

Veja a lista completa de ferramentas disponíveis na página Available MCP Tools.

Quando a Duvo lança um novo endpoint da Public API, ele se torna automaticamente uma ferramenta MCP no próximo deploy. Não há etapa de manutenção separada.

URL do servidor

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

O servidor usa o transporte Streamable HTTP do MCP (POST /v2/mcp). A maioria dos hosts MCP modernos suporta esse transporte nativamente.

Nota

O endpoint anterior https://api.duvo.ai/v1/mcp ainda funciona e serve as mesmas ferramentas que /v2/mcp, então configurações existentes continuam funcionando sem alterações — inclusive após o sunset da API /v1. Novas conexões devem usar /v2/mcp.

Autenticação

O servidor MCP da Duvo aceita dois tipos de credenciais:

Opção 1 — OAuth (recomendado para uso pessoal)

Recomendado para hosts que solicitam login (Claude Desktop, Cursor, conectores do ChatGPT). O host executa um login único baseado em navegador na Duvo e depois gerencia renovação e revogação de tokens para você. Sem chave de API para copiar ou rotacionar.

Os passos exatos dependem do host. Em geral:

Adicione `https://api.duvo.ai/v2/mcp` como a URL do servidor MCP nas configurações do seu host. O host detecta o desafio OAuth e abre uma aba do navegador para a página de login da Duvo. Faça login e aprove a conexão. O host armazena os tokens OAuth e os usa automaticamente em cada chamada de ferramenta.

O servidor MCP da Duvo publica seus metadados OAuth em https://api.duvo.ai/.well-known/oauth-protected-resource/v2/mcp (RFC 9728). Hosts MCP compatíveis usam isso para descobrir o servidor de autorização e se registrar automaticamente via Dynamic Client Registration.

Opção 2 — Chave de API (recomendado para scripts e contas de serviço)

Use chaves de API quando o host não suporta OAuth, ou para uso não interativo (CI, contas de serviço).

Gere uma chave no painel da Duvo em [Seu Perfil → Chaves de API](https://app.duvo.ai/settings/profile#api-keys), com escopo para um único time ou para todos os times que você pode acessar. Usuários com o papel de Gerente ou superior também podem criar chaves de um time em [Configurações do Time → Chaves de API](https://app.duvo.ai/settings/api-keys). Configure o host MCP para enviar a chave como um token bearer no cabeçalho `Authorization`:

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

O host pode então chamar as ferramentas MCP da Duvo sem nenhum login adicional.

As chaves de API têm escopo para um único time ou para todos os times que o proprietário pode acessar, e herdam as permissões do usuário que as gerou.

Configuração por host

O padrão MCP significa que a mesma URL da Duvo funciona em qualquer host compatível. A sintaxe de configuração difere ligeiramente entre produtos, então consulte o guia de configuração MCP do seu host para os nomes exatos dos campos. Padrões comuns:

Edite a configuração do Claude Desktop (`claude_desktop_config.json`):

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

Reinicie o Claude Desktop. Quando você mencionar a Duvo ou usar uma ferramenta do conector, o Claude Desktop abre uma aba do navegador para login OAuth.

Adicione o servidor da Duvo pelo seu terminal com o comando `claude mcp add`:

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

Na primeira vez que você chamar uma ferramenta da Duvo, o Claude Code executa o login OAuth baseado em navegador. Para usar uma chave de API em vez disso (para CI ou contas de serviço), passe-a como um cabeçalho bearer:

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

Nas configurações do Cursor, abra a seção de servidores MCP, adicione um novo servidor com a URL `https://api.duvo.ai/v2/mcp` e deixe o Cursor executar o fluxo OAuth. Adicione um Custom Connector apontando para `https://api.duvo.ai/v2/mcp`. O ChatGPT gerencia o Dynamic Client Registration e o fluxo OAuth automaticamente. Qualquer biblioteca de cliente compatível com MCP (TypeScript, Python, etc.) pode se conectar — aponte-a para `https://api.duvo.ai/v2/mcp`, forneça um token OAuth ou uma chave de API, e chame `tools/list` para descobrir o que está disponível.

Ergonomia das ferramentas

As ferramentas seguem a Public API subjacente:

Os nomes das ferramentas mapeiam para os operationIds do OpenAPI (por exemplo, listAgents, startRun, getConnection).
As descrições das ferramentas vêm da descrição OpenAPI de cada endpoint.
Os esquemas de entrada são planos — parâmetros de caminho, parâmetros de consulta e corpo da solicitação são mesclados em um único objeto para que as chamadas sejam lidas naturalmente (startRun({ agent_id: "...", input: "..." }) em vez de envolver cada seção).
As respostas correspondem à resposta da API correspondente. Use a Referência da Public API para as formas exatas.
Cada ferramenta carrega anotações MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), para que os hosts possam distinguir uma leitura de uma escrita e saber quais ferramentas alcançam fora da Duvo — por exemplo startRun, probeMcpServer, ou as ferramentas de início do OAuth.
Erros de não encontrado nomeiam o parâmetro de id que falhou e ecoam o valor que você enviou (por exemplo case_queue_id), para que uma chamada que recebe vários ids diga qual deles verificar.

Skills integradas

O servidor também entrega as Agent Skills da Duvo como recursos MCP, para que seu host tenha a mesma orientação sem instalar nada. Cada skill é um arquivo markdown em duvo://skills/:

Recurso	Use para
`duvo://skills/aop-writer/SKILL.md`	Rascunhar, reescrever ou criticar o AOP de um Agent
`duvo://skills/run-debugger/SKILL.md`	Descobrir por que um Run falhou ou produziu o resultado errado
`duvo://skills/workflow-debugger/SKILL.md`	Auditar um Agent ou um fluxo de trabalho conectado a Queue em muitos Runs
`duvo://skills/improve-agent/SKILL.md`	Levar um Agent de onde está até uma melhoria aplicada
`duvo://skills/improve-queue/SKILL.md`	Fazer o mesmo para uma Queue e o fluxo de trabalho produtor/consumidor ao redor dela
`duvo://skills/connection-doctor/SKILL.md`	Diagnosticar as Connections e Logins dos quais um Agent depende

As instruções do servidor dizem ao host quando ler cada skill, e os arquivos de referência ficam ao lado de cada SKILL.md em references/. Hosts que exibem recursos MCP (Claude Desktop, Claude Code, Cursor) os listam automaticamente.

Nota

As skills são o mesmo conteúdo do repositório público duvoai/skills, que você ainda pode instalar localmente para usar com a CLI da Duvo.

Limites e comportamento

Todos os limites de taxa da Public API se aplicam às chamadas de ferramentas MCP.
Cada chamada de ferramenta respeita as permissões do usuário autenticado, assim como uma chamada direta à API.
Runs de longa duração não são transmitidos via MCP atualmente — inicie o Run pela ferramenta e depois consulte getRun ou listRunMessages para monitorar o progresso.

Solução de problemas

Aviso

401 Não autorizado — Seu token está ausente, expirado ou para um público diferente. Execute o OAuth novamente ou regenere a chave de API no painel.

Aviso

403 Proibido — Sua conta não tem permissão para chamar este endpoint. Verifique seu papel no time e as permissões da Connection.

Aviso

OAuth não abre um navegador — O host pode não suportar Dynamic Client Registration. Use a autenticação por chave de API como alternativa, ou consulte a documentação do host para etapas de configuração do OAuth.

Privacidade e termos

Política de Privacidade — como a Duvo trata dados acessados pelo servidor MCP.
Termos de Uso — os termos que se aplicam ao uso da API e do MCP da Duvo.

Para detalhes abrangentes da plataforma (certificação SOC 2, criptografia, Zero Data Retention da Anthropic, subprocessadores), veja Segurança e Privacidade.

Relacionados

O catálogo completo de ferramentas que este servidor expõe. A outra direção: traga seu próprio servidor MCP para a Duvo. A API que o servidor MCP da Duvo encapsula. Wrapper focado em terminal sobre a mesma API.