mcp-dev-agent

Servidor MCP (Model Context Protocol) vía Streamable HTTP que proporciona a un agente de IA — consumido por un agente de Microsoft Copilot Studio — las mismas capacidades de desarrollo que un agente Claude Code tiene en esta VM: ejecutar comandos, editar/mover/listar archivos y usar node, npm, gh, git, etc. El agente decide qué comandos ejecutar.

Documentación

• docs/RECOMENDACAO.md — recomendaciones de arquitectura y próximos pasos antes de producción.

• docs/DEPLOY-CLOUDFLARE.md — exponer vía Cloudflare Tunnel (HTTPS público, sin abrir puertos).

• docs/CREDENCIALES.local.md — secreto, fuera del control de versiones (.gitignore): URL, token y datos del túnel en producción (mcp.criaelo.com).

Related MCP server: SkyDeckAI Code

Arquitectura

Copilot Studio (nuvem)
        │  HTTPS + Bearer token
        ▼
[ Reverse proxy / túnel com TLS ]   ← obrigatório: Copilot Studio exige HTTPS público
        │
        ▼
mcp-dev-agent  (Express + Streamable HTTP, porta 3000)
        │  child_process / fs
        ▼
  VM de desenvolvimento  (node, npm, gh, git, arquivos das aplicações)

• Transporte: Streamable HTTP (endpoint único POST/GET/DELETE /mcp), que es el modo en que Copilot Studio consume MCP.

• Autenticación (dos formas, ambas aceptadas en /mcp):

  • Bearer token estático vía header Authorization (variable MCP_AUTH_TOKEN) — usado por Copilot Studio.

  • OAuth 2.1 conforme a la spec de autorización de MCP (Dynamic Client Registration, authorization code + PKCE, refresh token) — exigido por ChatGPT. Endpoints: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource/mcp, /authorize, /token, /register, /revoke. La aprobación solicita la contraseña OAUTH_APPROVAL_PASSWORD (fallback: MCP_AUTH_TOKEN). Los clientes y tokens se guardan en data/oauth-state.json (fuera del control de versiones, chmod 600); implementación en src/oauth.ts.

• Alcance de archivos: sin restricción de ruta — el agente opera en cualquier ruta de la VM (decisión de proyecto). Resuelve ~ y rutas relativas.

Herramientas expuestas

run_command por sí solo ya cubre todo; las herramientas de archivo existen porque son más fiables y legibles para el agente que montar comandos de shell.

Ejecución

npm install
npm run build

# gere um token forte e exporte antes de iniciar
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export PORT=3000
# producao: URL publica HTTPS (issuer OAuth) e senha da tela de aprovacao
export PUBLIC_URL=https://seu-host
export OAUTH_APPROVAL_PASSWORD=uma-senha-forte
npm start

Desarrollo con recarga: npm run dev (también necesita MCP_AUTH_TOKEN).

Health check (sin autenticación): GET /health → { "status": "ok", "tools": [...] }.

Prueba rápida del handshake

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

El header de respuesta Mcp-Session-Id debe reenviarse en las llamadas siguientes (tools/list, tools/call).

Exponer con HTTPS (necesario para Copilot Studio)

Copilot Studio (nube) solo alcanza endpoints HTTPS públicos. Coloque el servidor detrás de TLS. Opciones:

• Proxy inverso (nginx/Caddy) con certificado, reenviando a http://127.0.0.1:3000.

• Túnel para exponer rápidamente: cloudflared, ngrok, o Azure Application Gateway / Front Door si la VM es Azure.

Mantenga el servidor MCP escuchando en 127.0.0.1 cuando haya un proxy delante, para no exponer el puerto HTTP crudo.

Conexión en Copilot Studio

Copilot Studio consume MCP a través de una tool/custom connector que apunta al endpoint Streamable HTTP:

1. En Copilot Studio, abra su agente → Tools → Add a tool → New tool → Model Context Protocol. (Alternativamente, Power Apps → Custom connectors e importe la spec a continuación.)

2. Server URL: la URL HTTPS pública que apunta a /mcp (ej.: https://su-host/mcp).

3. Autenticación: tipo API Key / header, con header Authorization y valor Bearer <su MCP_AUTH_TOKEN>. Guarde el token en el cofre/variable de entorno del connector, nunca en el prompt.

4. Guarde y publique el connector; añada la tool al agente.

5. Las 8 herramientas aparecen para el agente, que pasa a decidir por sí mismo cuándo llamar a run_command, edit_file, etc.

Nota: el soporte de MCP en Copilot Studio evoluciona rápido. Si la UI no ofrece MCP nativo en su región/licencia, cree un custom connector con una spec OpenAPI que describa el endpoint /mcp (Streamable HTTP) y el header Authorization.

Conexión en ChatGPT

ChatGPT exige OAuth (no acepta Bearer token estático) y requiere developer mode (Plus/Pro) o plan Business/Enterprise:

1. Settings → Connectors → Create (con developer mode habilitado en Settings → Connectors → Advanced).

2. MCP Server URL: https://su-host/mcp — Authentication: OAuth.

3. ChatGPT descubre los endpoints vía /.well-known/*, se registra solo (DCR) y abre la pantalla de aprobación: introduzca la OAUTH_APPROVAL_PASSWORD.

4. Listo — los access tokens duran 2 h y se renuevan automáticamente vía refresh token (30 días, con rotación).

Para revocar el acceso de ChatGPT: elimine data/oauth-state.json y reinicie el servicio (o use /revoke).

Seguridad — lea antes de producción

Este servidor ejecuta comandos arbitrarios en la VM. Consecuencias:

• Trate el MCP_AUTH_TOKEN como credencial de acceso root a la VM. Rote periódicamente.

• Ejecute el proceso con un usuario de bajo privilegio dedicado al desarrollo, no como root.

• Prefiera una VM desechable/aislada por proyecto; no apunte a máquinas con datos sensibles de otros sistemas.

• Siempre detrás de TLS; nunca exponga el puerto HTTP crudo en internet.

• Considere logs de auditoría de los comandos recibidos si necesita trazabilidad.