External Agent MCP integration

Use Manager AGI Agents as MCP tools from a trusted server-side application. This guide covers setup, authentication, downstream authorization, calls, recovery, and stable errors.

Quick start

1. In Web Admin, create an active third-party application, bind it to a company, and copy its App ID and App Secret.
2. Assign an enabled Agent to that company. Only enabled, assigned Agents with effective published Skills are listed.
3. Point an MCP Streamable HTTP client at POST|GET|DELETE /openapi/v1/agents/mcp on your Engine HTTPS host.
4. Initialize a session, send notifications/initialized, call tools/list, then call an agent_{id} tool.

The general assistant is not exported. Keep the App Secret on your server.

Authentication and authority scope

API environments:

• Test: https://aim-api-test.proton-system.com
• Production: https://aim-api.proton-system.com

Every request must include Authorization: Basic Base64(KEY:SECRET), where KEY is the App ID and SECRET is the App Secret. Also send the content-negotiation headers shown below.

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

A remote MCP client that supports custom request headers can use the following configuration:

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

An active third-party application is permanently approved at company scope: existing and newly assigned Agents and their newly published Skills become reachable without a human approval step, including write or high-risk operations. CompanyRole does not narrow this authority. The Engine still enforces application, company, Agent, assignment, Skill publication, downstream authorization, schema/risk drift, validation, rate limits, idempotency, and audit controls.

Initialize and manage a session

Initialize with a supported MCP protocol version, then save the Mcp-Session-Id response header.

{"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"}

Send Mcp-Session-Id on later POST, GET, and DELETE requests. Reinitialize after INVALID_MCP_SESSION.

Agent tools and metadata

Discover tools after initialization:

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

Each tool is named agent_{id}, using the exact Agent ID after the prefix. Its top-level title is the Agent name, and its description is the Agent description with the name as fallback. _meta.easyposAgent contains public id, name, description, and iconUrl. Its sibling authorizationRequirements contains deduplicated downstream requirements: mcpHubId, mcpHubName, authType, status, expiresAt, authorized, and, when authorization is needed, the Engine-owned authorizationUrl. Prompts, quick questions, Skill definitions, internal tool schemas, and credentials are not exposed.

Downstream authorization

When status is MISSING or REAUTH_REQUIRED, open the Engine-owned authorizationUrl, which starts at /openapi/v1/mcp/authorization/start. After the user finishes, retry tools/list or the original tools/call; ACTIVE means the Engine can execute with its stored application-scoped grant. Expiration or a downstream 401 returns an authorization error and requires the same flow again. Do not refresh tokens, send downstream headers, or automatically replay the failed business call.

Call an Agent

Use the exact tool name returned by tools/list. Add _meta.progressToken if you want standard MCP progress notifications.

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"Summarize today's open orders","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId is required, trimmed, and at most 128 UTF-8 bytes. message is required and at most 16 KiB. conversationId is optional and may only be reused by the same application, company, and Agent.

A successful tool result includes "status":"COMPLETED", "answer", requestId, conversationId, Agent display metadata, and current authorizationRequirements. Missing downstream credentials return isError:true, status:"authorization_required", and errorCode:"MCP_AUTHORIZATION_REQUIRED" without creating an execution.

SSE, resume, cancellation, and close

With Accept: application/json, text/event-stream, consume standard MCP progress notifications and one final tool result. To replay a disconnected stream, GET the same endpoint with Basic authentication plus Mcp-Session-Id, opaque Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id, and Accept: text/event-stream. Replay restores persisted events and never reruns the Agent; if more remain, repeat GET with the newest cursor.

An explicit MCP cancellation only requests cancellation, and dispatched side effects are not rolled back. A transport disconnect does not cancel accepted work. Close a session with authenticated DELETE and Mcp-Session-Id.

Limits and idempotency

requestId is idempotent within one application for 90 days. The same normalized input replays the stored/in-progress outcome without consuming another execution unit. Different input returns IDEMPOTENCY_CONFLICT; a still-running request may return REQUEST_IN_PROGRESS.

Error contract

Transport failures use an HTTP status and JSON such as {"code":"COMPANY_INACTIVE","description":"The company is inactive."}. MCP/domain failures use isError:true, errorCode, and errorDescription in structured Tool output. Descriptions are stable, non-sensitive English text; branch on the code.

Security and troubleshooting

Use TLS, store the App Secret in a secret manager, and redact authorization headers from logs. Never send the Secret from browser/mobile code, URLs, or source control. Server clients should omit Origin; if present, it must be an allowed HTTPS origin. Disable the application or reset its Secret after suspected exposure; existing sessions then become invalid.

If tools/list is empty, check company/Agent status, assignment, and effective published Skills. If authorization is required, open authorizationUrl and retry discovery or the call after completion. On invalid session, initialize again. The application's notification callbackUrl is not an Agent result channel: read execution results from MCP/SSE.