# Servidor MCP

Servidor MCP com OAuth e aprovação humana para que agentes de IA operem a ArduMaker, com perfis, repetições seguras e limites.

Fonte: https://ardumaker.com/pt/docs/servidor-mcp/

- Categoria: Inteligência artificial e agentes
- Estado: Disponível
- Requisitos: Uma conta ArduMaker para aprovar o acesso do agente; Um cliente compatível com MCP e OAuth (por exemplo Claude, ChatGPT ou Cursor); Acesso, como pessoa, às empresas, projetos e VPS que o agente vai usar
- Ferramentas MCP (Só leem): `ping`, `ver_contexto_inicial`, `listar_empresas`, `ver_operacion`

## O que permite fazer?

- Que um agente de IA opere a ArduMaker em nome de uma pessoa real: projetos, VPS, domínios, bases, correio, WordPress, deploys, túneis e mais.
- Escolher ao aprovar sobre que projetos e que VPS pode agir, e se é só de leitura.
- Ligar o mesmo agente a um subconjunto de ferramentas (um perfil) para não gastar contexto.
- Repetir criações sem duplicar nada, acompanhar operações longas e receber erros que dizem o que fazer.

## Quando convém usar?

- Delegar em um agente tarefas repetitivas de infraestrutura ou de gestão de projetos.
- Deixar um agente diagnosticar (logs, estado) com permissões só de leitura.
- Automatizar fluxos de vários passos (publicar um repo em um domínio, montar um túnel entre VPS) em uma única chamada.

## Como funciona na ArduMaker?

### Link e autorização

1. O cliente registra-se sozinho no servidor (`https://mcp.ardumaker.com`, registro dinâmico). Registar-se não dá nenhum acesso.
2. O cliente abre a autorização no navegador; a ArduMaker mostra que agente pede acesso. O pedido vive 10 minutos e é de uso único.
3. A pessoa aprova ou rejeita e escolhe o alcance: todos os projetos ou alguns, todos os VPS ou alguns (em separado), e se é só de leitura.
4. O cliente recebe um `access_token` (8 horas) e um `refresh_token` (30 dias, de uso único) e chama as ferramentas com OAuth 2.1 + PKCE.
5. Quando o access token expira, o cliente renova-o sozinho, sem voltar a pedir aprovação. A sessão dura no máximo 180 dias; depois é preciso voltar a autorizar.

Cada renovação entrega um refresh token novo e invalida o anterior. Se chegar um já usado, há uma cópia a circular: revoga-se a sessão inteira e marca-se a link. Aprovar de novo o mesmo cliente reutiliza a link e abre uma sessão nova.

### Descoberta

- Metadados OAuth em `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource`.
- `/tools.json`: a referência pública das ferramentas, sem autenticação. A versão legível está em [/mcp/docs](https://ardumaker.com/pt/mcp/docs).
- `ping` responde sem token; tudo o resto exige token.
- `tools/list` já vem filtrado: um agente só de leitura não vê as ferramentas que escrevem, e as de administração do sistema só aparecem se quem autorizou for admin do sistema.

### Contexto de empresa

A primeira chamada recomendada é `ver_contexto_inicial` (também como recurso `ardumaker://contexto-inicial`): diz quem autorizou o agente, que alcance tem, até 50 ids de empresas, projetos e VPS, quantos VPS vê no total e a lista do que nenhum agente pode fazer. As listas estão cortadas: se faltar algo, procura-se com `listar_empresas`, `listar_proyectos` ou `listar_todos_los_vps`.

### Leitura, escrita e ações sensíveis

- Cada ferramenta declara se só lê, se é destrutiva, se é idempotente e se toca o mundo exterior. Uma sem declaração é tratada como de escrita.
- As ferramentas chamam os mesmos serviços que o painel web, com as permissões da pessoa que autorizou: um agente nunca vê nem faz mais do que o seu humano.
- As ações de risco pedem uma confirmação explícita no argumento (`confirmado`, `confirmacion` com o nome exato) e algumas não existem por MCP (apagar um VPS, um projeto ou um registro DNS). Ver [Permissões do agente MCP](https://ardumaker.com/pt/docs/permisos-mcp).
- O que um terceiro escreveu (correios, comentários, logs, mensagens de commit, saída de comandos) chega envolvido como `{origen: "no_confiable", escrito_por, advertencia, contenido}`: é dado, nunca instruções.

### Repetições e operações longas

- Toda ferramenta que cria algo aceita `idempotency_key`. Repetir com a mesma chave e os mesmos argumentos devolve o resultado original marcado `idempotente: true`; a chave vale 24 horas. Reutilizá-la com outros argumentos é rejeitado.
- O que demora (criar um VPS, clonar um repo, ativar um domínio com SSL, instalar um papel de túnel) devolve um `operacion_id`. `ver_operacion` responde sempre igual: `estado` `en_curso`, `ok` ou `error`, e `reintentar_en_segundos` enquanto corre.
- O resultado de uma operação terminada fica disponível alguns dias, por isso após uma desconexão recupera-se com `ver_operacion` em vez de repetir nada.

## O que muda realmente?

- Ao aprovar cria-se uma link entre a pessoa e o cliente; vê-se e gerencia-se em `/me` (agentes ligados).
- Cada chamada fica registrada (ver [Auditoria de agentes](https://ardumaker.com/pt/docs/auditoria-de-agentes)).
- O que o agente modifica muda na ArduMaker tal como se a pessoa o fizesse a partir do painel, e fica em nome do agente e de quem o autorizou.

## Perfis

| Rota | O que serve |
| --- | --- |
| `/mcp` | Tudo; nunca muda |
| `/mcp/vps` | VPS, domínios e nginx, usuários Linux, systemd, tarefas, bases, deploys, túneis, logs e Apps |
| `/mcp/proyectos` | Projetos, etapas, tarefas, checklists, comentários, anexos, calendário, reuniões e lixeira |
| `/mcp/infra` | Correio, domínios e DNS, blogs, estado de cobrança, chaves de RouterIA e Search API, sandbox e webhooks de WhatsApp |
| `/mcp/wordpress` | Sites WordPress, WooCommerce e Elementor, mais `instalar_app` e `listar_vps` |

Um mesmo token vale em todos os perfis: mudar de perfil é mudar o URL. `ping`, `ver_contexto_inicial`, `ver_operacion` e `listar_empresas` estão em todos.

## Limites

| Limite | Valor | O que acontece ao passá-lo |
| --- | --- | --- |
| Chamadas por link | 10 por segundo | `limite_excedido` com `reintentar_en_segundos`; a rejeição não gasta quota |
| Listas em uma resposta | 200 elementos | É cortada e acrescenta-se `<chave>_recortado` com o total real |
| `limit` fora do intervalo | O máximo de cada ferramenta | É ajustado e avisado em `limit_ajustado` |
| Comandos em um VPS | 10 por segundo por VPS; saída de 20000 caracteres; espera de 10 a 300 s | Rejeição ou saída truncada (`truncated: true`) |
| Alterações DNS | 10 por minuto por empresa | 429 |
| Cópias de VPS à mão | 1 por hora por VPS | 429 |

Algumas ferramentas têm limites próprios mais baixos, indicados na sua descrição.

## Esquema

**Uma chamada a uma ferramenta**

```text
Cliente MCP (token Bearer da sessão)
  ↓
Auditoria (envolve tudo: também as rejeições ficam registradas)
  ↓
Limite por link (10 chamadas por segundo)
  ↓
Proteções (só leitura, admin do sistema, idempotência)
  ↓
Ferramenta (mesmo serviço que o painel, com o alcance em tempo real)
  ↓
Resposta (dados, ou erro estruturado)
```

## Resultado esperado

- No cliente aparecem as ferramentas do perfil escolhido, já filtradas pelo alcance.
- `ver_contexto_inicial` confirma em nome de quem o agente age e o que pode fazer.
- Em `/me` vê-se a link: ativa ou não, último uso, até quando dura a sessão e o que o agente está fazendo.

## Erros e resolução

Todo erro chega com a mesma forma, sem rastos internos:

```json
{
  "error": true,
  "code": "parametro_invalido",
  "que_paso": "...",
  "que_hacer": "...",
  "reintentable": false,
  "detalle": { "fields": { "...": "..." } }
}
```

| `code` | Significa | Repetível? |
| --- | --- | --- |
| `no_encontrado` | O id não existe; pode trazer `candidatos` válidos | No |
| `sin_permiso` | A pessoa, o alcance ou a regra do MCP não o permitem | No |
| `parametro_invalido` | Um argumento está mal; `detalle` diz qual | No |
| `conflicto` | É preciso mudar um argumento (por exemplo, confirmar) | No |
| `estado_invalido` | O mundo não está pronto: VPS desligado, serviço externo em baixo | Sim |
| `limite_excedido` | Passou-se um limite; esperar `reintentar_en_segundos` | Sim |
| `interno` | Erro inesperado; traz `correlacion_id` para o reportar | Sim, uma vez |

- `reintentable: true` significa que repetir a MESMA chamada, sem mudar nada, pode funcionar.
- Em OAuth, `invalid_grant` com `Refresh token already used; the session was revoked` indica reutilização detetada: é preciso voltar a autorizar.
- Um timeout de um comando (`agente_timeout`) não significa que não correu: convém verificar antes de o repetir.

## Relação com MCP

Este documento é sobre o próprio servidor MCP. A referência de cada ferramenta (parâmetros, se lê ou escreve, se é destrutiva) está em [/mcp/docs](https://ardumaker.com/pt/mcp/docs), e a apresentação com exemplos por área em [/mcp](https://ardumaker.com/pt/mcp).

- Ferramentas comuns: `ping` (sem autenticação), `ver_contexto_inicial`, `listar_empresas`, `ver_operacion`.
- Para instalar algo em um VPS, a ordem recomendada é: `instalar_app` para o que o catálogo oferece; a configuração de deploy (`guardar_config_deploy_app`) para os processos de uma app de Git; `crear_servicio_vps` e `crear_tarea_vps` para o resto; `ejecutar_comando_vps` só se nada do anterior servir.

## Funcionalidades relacionadas

- [Permissões do agente MCP](https://ardumaker.com/pt/docs/permisos-mcp/)
- [Auditoria de agentes](https://ardumaker.com/pt/docs/auditoria-de-agentes/)
- [Chaves de IA](https://ardumaker.com/pt/docs/claves-ia/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)
- [Projetos e quadro kanban](https://ardumaker.com/pt/docs/proyectos-kanban/)