Gateway data-plane API

Every endpoint agents call on the MAQPNA gateway - MCP, A2A, model calls, egress proxy and probes - with headers, bodies, status codes, reason values and curl examples.

This page is the reference for the HTTP API that agents and their SDKs call on the MAQPNA gateway: Model Context Protocol (MCP) tool calls on /mcp, agent-to-agent (A2A) calls on /a2a, model calls on /llm, the browser egress proxy, and the health, readiness, version and metrics endpoints. The admin API (/v1/*) has its own page: Admin API. Session tokens come from the identity broker: Identity broker API.

Use this page when you write an agent without an SDK, debug what an SDK sends, or build a client in a language MAQPNA has no SDK for. For a task-first introduction, read Connect to the gateway and Tool calls over MCP first.

Source: cmd/maqpna-gateway (route table in server.go and the register*Routes functions).

Endpoints at a glance#

The session-scoped endpoints that sandbox tools use (/v1/sessions/{id}/exec, /files, /evidence, /tools:authorize, /infra:*, /liveview) accept a session token too. They are listed with the rest of /v1/sessions/* in the Admin API.

Auth model#

Every data-plane call carries a session token: a short-lived, Ed25519-signed token that the identity broker issued for one session. The gateway verifies it against the broker's public keys (JWKS), checks the scope for the target, and forwards the call with its own credential for the MCP server or model endpoint. The agent's Authorization header is never forwarded.

sequenceDiagram
    autonumber
    participant OP as Operator
    participant IB as Identity broker
    participant AG as Agent (sandbox)
    participant GW as Gateway
    participant UP as MCP server / model
    OP->>IB: POST /v1/token (namespace, agent, session, user, scopes)
    IB-->>OP: session token (Ed25519 JWS)
    OP->>AG: token file (MAQPNA_TOKEN_FILE)
    GW->>IB: GET /.well-known/jwks.json (every 300 s, and on an unknown kid)
    AG->>GW: POST /mcp/github<br/>Authorization: Bearer <session token>
    GW->>GW: verify signature, aud, exp, revocation,<br/>scope tools:github, DLP, policy, budget
    GW->>UP: tools/call with the gateway's credential<br/>+ X-Maqpna-Namespace, -Agent, -Session, -User
    UP-->>GW: result
    GW->>GW: response DLP, taint, audit record
    GW-->>AG: JSON-RPC result

Token presentation#

The gateway also accepts access tokens from external identity providers listed in identity.trustedIssuers (external MCP clients). A missing token on /mcp returns 401 with a WWW-Authenticate header that points at the RFC 9728 metadata document.

Scopes#

A granted scope may be a glob (tools:*, models:coder-*). See Identity and delegation.

Session-token claims the gateway reads#

The full claim table is on the Identity broker API page.

Common error envelope#

Every error the gateway generates carries the same fields, wherever the protocol puts them. Clients match on the reason token (the text before the first :), never on message or detail.

Where the envelope lives:

A denied MCP call:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32001,
    "message": "denied by policy default-agent-policy rule destructive-needs-human: approval_denied by [email protected] (apr-3f9c)",
    "data": {
      "domain": "maqpna.com",
      "reason": "approval_denied",
      "detail": "approval_denied by [email protected] (apr-3f9c)",
      "policy": "default-agent-policy",
      "rule": "destructive-needs-human"
    }
  }
}

The values are illustrative; the field names, the code and the message pattern (denied by policy <policy> rule <rule>: <reason>) come from the gateway. The complete list of reason tokens, their groups and how a client should react to each is in Error envelope and reason codes and Error and reason codes.

JSON-RPC codes#

MCP: /mcp/{server}#

The gateway speaks MCP over streamable HTTP. {server} is the name of an MCP server visible to the caller's namespace (an MCPServer resource rendered into the gateway's registry), or a built-in server (maqpna-web, memory, maqpna-k8s). Supported revisions: 2025-03-26, 2025-06-18, 2025-11-25 and 2026-07-28.

POST /mcp/{server}#

Send one JSON-RPC message or a batch (a JSON array).

Request headers

The X-Maqpna-* request headers are removed before the call is forwarded.

Methods and how the gateway handles them

Request IDs must be a string or an integer. Other IDs (null, fractions, booleans, objects) get -32600. In a batch, request IDs must be unique.

Example: call a tool

curl -sS "$MAQPNA_GATEWAY_URL/mcp/echo" \
  -H "Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hello"}}}'

An allowed call returns the MCP server's result unchanged, except for DLP redactions:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"hello"}]}}

Approvals. When a rule says require_approval, the gateway holds the call:

• Synchronous (default). The HTTP request stays open until an approver decides or the approval expires (approvalTimeoutSeconds, default 300). Approved: the call runs once and you get its result. Denied or expired: -32001 with reason approval_denied or approval_expired.
• Asynchronous (X-Maqpna-Async: 1). The gateway answers at once:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "approval required (destructive); retry with header X-Maqpna-Approval-Id once approved",
    "data": {
      "domain": "maqpna.com",
      "reason": "approval_required",
      "detail": "destructive",
      "approvalId": "apr-3f9c",
      "expiresAt": "2026-10-18T14:10:00Z",
      "policy": "default-agent-policy",
      "rule": "destructive-needs-human"
    }
  }
}

Retry the same call (same tool, same arguments) with X-Maqpna-Approval-Id: apr-3f9c. While the approval is pending you get -32002 again; once approved the call runs and the approval is consumed (single use). An approval ID for another call gets -32001 with reason approval_invalid.

• MCP 2026-07-28 clients get an InputRequiredResult instead of -32002, whose requestState (maqpna-approval:<id>) the client echoes on retry.

A session can hold at most 20 pending approvals; the next held call is denied with approval_quota_exceeded. An identical pending call reuses its existing approval.

Tool pinning. The gateway hashes every tool definition it sees in tools/list and compares it with the pins of the caller's policies (ToolPolicy.spec.toolPins) or of the MCPServer:

A tools/call for a tool the gateway has not seen listed triggers one upstream tools/list (at most every pinCacheSeconds, default 60 s). See MCP servers and tool pinning.

Status codes

GET /mcp/{server} and DELETE /mcp/{server}#

GET opens the server-to-client SSE stream of the streamable HTTP transport; DELETE ends the MCP session named by Mcp-Session-Id. Both need the session token and the tools:{server} scope, are checked against the kill switch, and are proxied with the gateway's credential. Server-initiated messages on the stream pass DLP.

curl -N "$MAQPNA_GATEWAY_URL/mcp/echo" \
  -H "Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")" \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: <session id from initialize>"

Built-in server memory#

POST /mcp/memory serves governed long-term memory with the tools memory_put {key, value, tags?}, memory_get {key}, memory_search {query, limit?} and memory_delete {key}. It needs scope tools:memory and a memory store bound to the caller's agent. Values are never written to the audit ledger; the record holds the store and the value's SHA-256. Without a store you get memory_backend_unavailable.

GET /.well-known/oauth-protected-resource/mcp/{server}#

RFC 9728 protected-resource metadata for external MCP clients that authenticate with your identity provider. It is served only when identity.trustedIssuers is configured and an issuer allows the server; otherwise 404.

{
  "resource": "https://gateway.example.eu/mcp/github",
  "authorization_servers": ["https://sso.example.eu/realms/acme"],
  "scopes_supported": ["tools:github"],
  "bearer_methods_supported": ["header"],
  "resource_name": "MAQPNA governed MCP server github"
}

A2A: /a2a/{ns}/{agent}#

Agents call other agents through the gateway. {ns}/{agent} is a hosted agent with spec.a2a.expose or an A2APeer (a remote agent). The gateway governs A2A v1.0 and accepts A2A 0.3 method names, which it governs as their v1.0 equivalents. The upstream always receives JSON-RPC; the HTTP+JSON binding is translated.

Every call needs scope agents:<agent> (agents:<ns>/<agent> across namespaces), must come from a caller in the target's allowedCallers, and is governed like a tool call: policy with server a2a/<agent> (a2a/<ns>/<agent> across namespaces) and tool SendMessage, skill:<id> or the method name; approvals, DLP, taint, budgets, the kill switch and the audit ledger apply. Both hops are audited.

Request headers

POST /a2a/{ns}/{agent} (JSON-RPC binding)#

curl -sS "$MAQPNA_GATEWAY_URL/a2a/team-a/reviewer" \
  -H "Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"ROLE_USER","messageId":"m-1","parts":[{"text":"Review PR 4821"}]}}}'

The answer is the callee's JSON-RPC response. Errors use the envelope in error.data.

/a2a/{ns}/{agent}/{rest...} (HTTP+JSON binding)#

A unary answer is the result object with 200; streams are SSE streams of the bare response objects. Errors are google.rpc.Status:

{"error":{"code":403,"status":"PERMISSION_DENIED","message":"denied by policy budget rule agent-day: budget_exceeded:agent/day","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"BUDGET_EXCEEDED","domain":"maqpna.com","metadata":{"jsonrpcCode":"-32001","policy":"budget","reason":"budget_exceeded:agent/day","rule":"agent-day"}}]}}

A pending approval on this binding is 409 with status ABORTED.

Agent card#

GET /a2a/{ns}/{agent}/.well-known/agent-card.json returns the card of a hosted agent, or a gateway-issued proxy card of a verified remote peer. It needs a session token with the agents: scope for that agent, unless a2a.publicCards is true. The card lists two interfaces, both at <publicURL>/a2a/{ns}/{agent}: JSONRPC and HTTP+JSON, protocol version 1.0, and a Bearer security scheme. With a2a.cardSigningKey set, the card is signed (JWS over the RFC 8785 canonical form) and the keys are published at GET /a2a/jwks.json (Cache-Control: public, max-age=300; 404 when signing is off).

curl -sS "$MAQPNA_GATEWAY_URL/a2a/team-a/reviewer/.well-known/agent-card.json" \
  -H "Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")"

Push notifications#

A push-notification config names a webhook the callee posts task updates to, bypassing the gateway. The gateway therefore refuses every webhook URL (in CreateTaskPushNotificationConfig and in a send's configuration) that is not https to a host matching a2a.pushNotificationHosts. With no hosts configured, push notifications are refused. The reason is push_url_not_allowed.

A2A reasons#

unknown_agent, caller_not_allowed, unknown_skill, unknown_method, delegation_depth (act chain longer than a2a.maxDelegationDepth, default 5), delegation_loop, callee_revoked, peer_card_unverified, push_url_not_allowed. See Agent-to-agent calls.

Model calls: /llm/{route}#

{route} is a model route rendered from the agent's spec.model (or a static models entry). Every model call needs scope models:<route>; the route may also restrict namespaces and agents. The gateway meters tokens and cost, runs DLP and injection guards on prompts and completions, enforces budgets and tokensPerMinute, and fails over to the route's fallbacks. With modelPolicy: policy it also evaluates your policies (server llm/<route>, tool = the operation, for example chat.completions); a require_approval result is a denial, because model calls cannot wait for approvals.

Wire formats#

The governance pipeline always runs on the client's wire format. Just before the upstream call, the endpoint's provider adapter turns the request into the provider's API, and the response back:

Point an SDK at the route: OpenAI SDKs use base URL $MAQPNA_GATEWAY_URL/llm/<route>/v1; Anthropic SDKs use ANTHROPIC_BASE_URL=$MAQPNA_GATEWAY_URL/llm/<route>/anthropic. The session token is the API key.

curl -sS "$MAQPNA_GATEWAY_URL/llm/team-a.coder/v1/chat/completions" \
  -H "Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Say hello"}]}'

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MAQPNA_GATEWAY_URL"] + "/llm/team-a.coder/v1",
    api_key=open(os.environ["MAQPNA_TOKEN_FILE"]).read().strip(),
)
r = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Say hello"}])
print(r.choices[0].message.content)

Anthropic wire format:

curl -sS "$MAQPNA_GATEWAY_URL/llm/claude/anthropic/v1/messages" \
  -H "x-api-key: $(cat "$MAQPNA_TOKEN_FILE")" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":256,"messages":[{"role":"user","content":"Say hello"}]}'

The response is the provider's answer in the client's wire format. For streaming chat completions the gateway may add stream_options.include_usage to meter the stream; it then drops the usage-only final chunk if the client did not ask for it.

Provider-hosted tools. A request that asks the provider to call MCP servers itself (Anthropic mcp_servers / mcp_toolset, OpenAI Responses mcp tools) is denied with provider_hosted_mcp. A provider-hosted server tool (web search or fetch, code execution, file search, computer use, image generation, Gemini grounding, Bedrock system tools) is denied with provider_hosted_tool:<name> unless the route's providerTools lists it.

Errors#

{"error":{"message":"agent budget (day) exhausted for team-a/coder: spent 10.000412 of 10.000000 USD","type":"maqpna_budget_exceeded","code":"budget_exceeded","reason":"budget_exceeded","domain":"maqpna.com"}}

code keeps its pre-v0.1.0 value for OpenAI-SDK compatibility; reason is the published token. See Model calls and LLM call governance.

Egress proxy#

With egress.enabled, the gateway's data listener is also an HTTP forward proxy for browser-profile sandboxes. CONNECT requests (HTTPS tunnels) and absolute-form requests (plain HTTP) are governed here instead of being routed to the API. The browser sidecar's relay adds the session token.

Each request is:

1. Authenticated: Proxy-Authorization: Bearer <session token> (or Basic with the token as password), scope tools:maqpna-egress, and the kill switch.
2. Checked against the URL rules and the domain policy (the agent's spec.browser.allowedDomains).
3. Evaluated by your policies with server maqpna-egress and tool connect or http (arguments host, port, method, url). require_approval is enforced as a denial.
4. Dialled through the guarded transport (SSRF block list, rebinding-safe DNS, residency check) and audited.

curl -sS -x "$MAQPNA_GATEWAY_URL" \
  --proxy-header "Proxy-Authorization: Bearer $(cat "$MAQPNA_TOKEN_FILE")" \
  https://docs.example.eu/

DPoP-bound tokens cannot be used at the proxy (dpop_proxy): a proxy request cannot carry a proof.

Health, readiness, version and metrics#

GET /healthz#

Liveness. Always 200 while the process serves.

curl -sS "$MAQPNA_GATEWAY_URL/healthz"

{"status":"ok"}

GET /readyz#

Readiness. 200 with {"status":"ready"} when policies are loaded, the gateway has identity verification keys, and the revocation list, state backend and audit ledger are healthy. Otherwise 503 with the list of problems. A draining replica answers 503 with shutting down.

{"status":"not ready","problems":["policies not loaded","no identity verification keys"]}

Other checks (audit ledger, governance stores) add their own problem texts. The common ones:

GET /version#

Build information. Hidden (404) on the public listener when adminListen is set.

{"component":"gateway","version":"2.1.0","commit":"<commit>","buildDate":"<date>","goVersion":"<go version>","platform":"linux/amd64"}

The fields are component, version, commit, buildDate, goVersion, platform and tags; the values above are placeholders.

GET /metrics#

Prometheus text format (text/plain; version=0.0.4). Hidden (404) on the public listener when adminListen is set; then scrape the admin listener. The metric families are listed in Metrics.

curl -sS "$MAQPNA_GATEWAY_URL/metrics" | grep maqpna_gateway_requests_total

Request limits#

Every response carries X-Content-Type-Options: nosniff. Browser origins are allowed only when listed in the gateway's CORS settings; preflight allows GET, POST, DELETE, OPTIONS with Authorization, Content-Type.

Next steps#

• Admin API: approvals, audit, sessions, kill switch and every other /v1/* route
• Identity broker API: how session tokens are minted, exchanged and verified
• Handle decisions: what your agent should do with each reason
• Gateway configuration: every gateway.json key named on this page
• Gateway request pipeline: the order of checks behind each call