Integración externa de Agent MCP

Use los Agents de Manager AGI como herramientas MCP desde una aplicación de servidor de confianza. Esta guía cubre configuración, autenticación, autorización descendente, llamadas, recuperación y errores estables.

Inicio rápido

1. Cree y active una aplicación de terceros en Web Admin, vincúlela a una empresa y copie App ID y App Secret.
2. Asigne a la empresa un Agent habilitado con Skills publicadas efectivas.
3. Conecte el cliente MCP Streamable HTTP a POST|GET|DELETE /openapi/v1/agents/mcp en el host HTTPS del Engine.
4. Inicialice, envíe notifications/initialized, consulte tools/list y llame a agent_{id}.

El asistente general no se publica. Mantenga el secreto solo en el servidor.

Autenticación y alcance de autoridad

Entornos de API:

• Pruebas: https://aim-api-test.proton-system.com
• Producción: https://aim-api.proton-system.com

Cada solicitud debe incluir:

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

Un cliente MCP remoto que admita encabezados de solicitud personalizados puede usar la siguiente configuración:

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

La aplicación activa obtiene aprobación permanente en el ámbito de la empresa. Los Agents asignados ahora o en el futuro y sus nuevas Skills publicadas quedan accesibles sin aprobación humana, incluso para operaciones de escritura o alto riesgo. CompanyRole no limita esa autoridad. El Engine sigue comprobando estados, asignación, publicación, autorización descendente, deriva de esquema/riesgo, validación, límites, idempotencia y auditoría.

Inicialización y sesión

Inicialice y guarde el encabezado de respuesta Mcp-Session-Id:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

Incluya Mcp-Session-Id en POST, GET y DELETE posteriores. Tras INVALID_MCP_SESSION, inicialice de nuevo.

Herramientas Agent y metadatos

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Cada herramienta se llama agent_{id} y usa el ID completo del Agent tras el prefijo. El title de nivel superior es el nombre del Agent y la descripción usa su descripción, o el nombre si está vacía. _meta.easyposAgent expone únicamente id, name, description e iconUrl. authorizationRequirements incluye mcpHubId, mcpHubName, authType, status, expiresAt, authorized y, cuando hace falta autorización, el authorizationUrl generado por Engine. No expone prompts, preguntas rápidas, definiciones de Skills, esquemas internos ni credenciales.

Autorización descendente

Cuando status sea MISSING o REAUTH_REQUIRED, abra el authorizationUrl generado por Engine, cuya ruta empieza por /openapi/v1/mcp/authorization/start. Tras completar la autorización, la aplicación vuelve a intentar tools/list o el tools/call original; ACTIVE indica que Engine puede ejecutar con la autorización guardada para esa aplicación. Una caducidad o un 401 exige repetir el flujo. No se renuevan tokens, no se envían cabeceras posteriores y no se repite automáticamente la operación fallida.

Llamar a un Agent

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"Resume los pedidos abiertos de hoy","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId es obligatorio, se recorta y admite 128 bytes UTF-8; message es obligatorio y admite 16 KiB; conversationId es opcional y solo puede reutilizarse con la misma aplicación, empresa y Agent. _meta.progressToken habilita progreso MCP estándar.

El resultado correcto incluye "status":"COMPLETED", "answer", requestId, conversationId, metadatos y authorizationRequirements. Si faltan credenciales descendentes, devuelve isError:true, status:"authorization_required" y errorCode:"MCP_AUTHORIZATION_REQUIRED" sin crear una ejecución.

SSE, reanudación, cancelación y cierre

Consuma progreso MCP y un resultado final. Para recuperar el stream, haga GET autenticado con Mcp-Session-Id, el cursor opaco Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id y Accept: text/event-stream. La recuperación no vuelve a ejecutar el Agent; repita GET con el cursor nuevo si quedan eventos.

La cancelación MCP explícita solo solicita cancelar y no revierte efectos ya enviados. Un transport disconnect no cancela trabajo aceptado. Cierre la sesión con DELETE autenticado y Mcp-Session-Id.

Límites e idempotencia

requestId es idempotente por aplicación durante 90 días. La misma entrada reproduce el resultado sin otra unidad de ejecución; una entrada distinta da IDEMPOTENCY_CONFLICT y una solicitud activa puede dar REQUEST_IN_PROGRESS.

Contrato de errores

Los errores de transporte usan HTTP y JSON como {"code":"COMPANY_INACTIVE","description":"The company is inactive."}. Los errores MCP/dominio usan isError:true, errorCode y errorDescription. La descripción es texto inglés estable y no sensible; la lógica debe usar el código.

Seguridad y diagnóstico

Use TLS y un gestor de secretos; elimine los encabezados de autorización de los logs. No exponga el App Secret en navegador, móvil, URL o repositorio. Los clientes de servidor deben omitir Origin; si existe, debe ser un origen HTTPS permitido. Ante una fuga, desactive la aplicación o restablezca el Secret.

Si tools/list está vacío, revise empresa, Agent, asignación y Skills publicadas. Si se requiere autorización, abra authorizationUrl y reintente el descubrimiento o la llamada al completarla; reinicialice una sesión inválida. El callbackUrl de notificaciones no recibe resultados del Agent: léalos por MCP/SSE.