Servidor MCP

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.
• 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.
• 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).
• 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

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

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

Esquema

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:

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

• 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, e a apresentação com exemplos por área em /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
• Auditoria de agentes
• Chaves de IA
• Servidores VPS
• Projetos e quadro kanban