Integração externa do Agent MCP

Use Agents do Manager AGI como ferramentas MCP em uma aplicação de servidor confiável. Este guia cobre configuração, autenticação, autorização downstream, chamadas, recuperação e erros estáveis.

Início rápido

1. No Web Admin, crie e ative uma aplicação de terceiros, vincule uma empresa e copie App ID e App Secret.
2. Atribua à empresa um Agent ativo com Skills publicadas efetivas.
3. Conecte o cliente MCP Streamable HTTP a POST|GET|DELETE /openapi/v1/agents/mcp no host HTTPS do Engine.
4. Inicialize, envie notifications/initialized, consulte tools/list e chame agent_{id}.

O assistente geral não é publicado. Mantenha o Secret apenas no servidor.

Autenticação e escopo de autoridade

Ambientes da API:

• Teste: https://aim-api-test.proton-system.com
• Produção: https://aim-api.proton-system.com

Cada solicitação deve incluir:

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

Um cliente MCP remoto que aceite cabeçalhos de solicitação personalizados pode usar a seguinte configuração:

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

A aplicação ativa recebe aprovação permanente no escopo da empresa. Agents atribuídos agora ou depois e novas Skills publicadas tornam-se acessíveis sem aprovação humana, inclusive operações de escrita ou alto risco. CompanyRole não reduz essa autoridade. O Engine ainda valida estados, atribuição, publicação, autorização downstream, mudanças de schema/risco, entrada, limites, idempotência e auditoria.

Inicialização e sessão

Inicialize e salve o header de resposta 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"}

Envie Mcp-Session-Id nos POST, GET e DELETE seguintes. Após INVALID_MCP_SESSION, inicialize novamente.

Ferramentas Agent e metadados

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

Cada ferramenta se chama agent_{id} e usa o ID completo do Agent após o prefixo. O title de nível superior é o nome do Agent; a descrição usa a descrição do Agent ou, se vazia, o nome. _meta.easyposAgent expõe somente id, name, description e iconUrl. authorizationRequirements inclui mcpHubId, mcpHubName, authType, status, expiresAt, authorized e, quando a autorização é necessária, o authorizationUrl gerado pelo Engine. Prompts, perguntas rápidas, definições de Skills, schemas internos e credenciais não são expostos.

Autorização downstream

Quando status for MISSING ou REAUTH_REQUIRED, abra o authorizationUrl gerado pelo Engine, cujo caminho começa em /openapi/v1/mcp/authorization/start. Após o usuário concluir, a aplicação tenta novamente tools/list ou o tools/call original; ACTIVE indica que o Engine pode executar com a autorização armazenada no escopo da aplicação. Expiração ou um 401 exige repetir o fluxo. Não renove tokens, não envie headers downstream e não repita automaticamente a operação que falhou.

Chamar um Agent

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

requestId é obrigatório, aparado e limitado a 128 bytes UTF-8; message é obrigatório e limitado a 16 KiB; conversationId é opcional e só pode ser reutilizado pela mesma aplicação, empresa e Agent. _meta.progressToken ativa o progresso MCP padrão.

O sucesso inclui "status":"COMPLETED", "answer", requestId, conversationId, metadados e authorizationRequirements. Sem credenciais downstream, retorna isError:true, status:"authorization_required" e errorCode:"MCP_AUTHORIZATION_REQUIRED" sem criar execução.

SSE, retomada, cancelamento e encerramento

Consuma o progresso MCP e um resultado final. Para recuperar o stream, faça GET autenticado com Mcp-Session-Id, cursor opaco Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id e Accept: text/event-stream. A recuperação não reexecuta o Agent; repita GET com o cursor novo se necessário.

O cancelamento MCP explícito apenas solicita o cancelamento e não reverte efeitos enviados. Um transport disconnect não cancela trabalho aceito. Encerre com DELETE autenticado e Mcp-Session-Id.

Limites e idempotência

requestId é idempotente por aplicação por 90 dias. A mesma entrada reproduz o resultado sem nova unidade de execução; entrada diferente retorna IDEMPOTENCY_CONFLICT e uma solicitação ativa pode retornar REQUEST_IN_PROGRESS.

Contrato de erros

Erros de transporte usam HTTP e JSON como {"code":"COMPANY_INACTIVE","description":"The company is inactive."}. Erros MCP/domínio usam isError:true, errorCode e errorDescription. A descrição é texto inglês estável e não sensível; use o código na lógica.

Segurança e solução de problemas

Use TLS e um gerenciador de segredos; remova headers de autorização dos logs. Não exponha o App Secret em navegador, app móvel, URL ou repositório. Clientes de servidor devem omitir Origin; se presente, deve ser uma origem HTTPS permitida. Em caso de vazamento, desative a aplicação ou redefina o Secret.

Se tools/list estiver vazio, verifique empresa, Agent, atribuição e Skills publicadas. Se a autorização for exigida, abra authorizationUrl e tente novamente a descoberta ou chamada após concluí-la; reinicialize sessão inválida. O callbackUrl de notificações não recebe resultados do Agent: leia-os por MCP/SSE.