How AI agents discover and call your APIs — a technical walkthrough with Zerq

This post is for engineers who need to understand the request path end-to-end: how an MCP client establishes a session, lists tools, and executes a real HTTP operation through Zerq without a parallel integration stack. It mirrors how Gateway MCP is documented in Zerq’s product documentation—conceptual detail here; exact URL paths and environment variables follow your deployment and docs version.

If you are new to MCP itself, read What is the Model Context Protocol (MCP) and why should every API team care? first.

Mental model: Gateway MCP vs Management MCP

Zerq exposes two MCP surfaces:

Surface	Typical caller	Purpose
Gateway MCP	AI agents, IDEs, assistants calling published APIs	`tools/list` → discover endpoints; `tools/call` → execute through the gateway
Management MCP	Operators, CI, Zerq Copilot changing platform config	Collections, proxies, workflows—same RBAC as the admin UI

This walkthrough focuses on Gateway MCP—the path API consumers use. For operations, see Platform automation.

Transport and session

Gateway MCP speaks JSON-RPC over HTTP to the gateway MCP endpoint (commonly under the same host as your API traffic, e.g. a path like /mcp—confirm in your environment). A typical flow:

initialize — Client and server agree on protocol version and capabilities.
Session — The server returns an Mcp-Session-Id (or equivalent) that clients must send on subsequent requests.
tools/list — Returns available tools for the authenticated context.
tools/call — Invokes a named tool with arguments (e.g. execute a specific published endpoint with params).

Some deployments also support SSE (GET) streams for long-lived sessions—check your ops docs for what is enabled in your build.

Headers: the same gateway context as REST

Gateway MCP requests are not exempt from identity. Clients send the same context you use for ordinary gateway calls—commonly including:

X-Client-ID — Which API client (application / partner identity) is acting.
X-Profile-ID — Which access profile (e.g. sandbox vs production) applies.
Authorization — The profile’s gateway credential (e.g. Bearer token), aligned with the Developer Portal testing console.

That alignment matters: a tool call should not use a different secret than what the partner would use in production integrations—otherwise you are testing fiction.

The four Gateway MCP tools (conceptual)

Zerq’s Gateway MCP surface exposes tools that map directly to discovering and running published work:

Tool	Role
`list_collections`	Collections the caller may see, with signals like published endpoint counts
`list_endpoints`	Flat list of published proxies—paths, methods, identifiers for later calls
`endpoint_details`	Schemas, examples, params—what agents need to construct valid requests
`execute_endpoint`	Runs a real gateway request—subject to rate limits, logging, and policy; errors surface as tool results

Nothing here replaces your upstream validation; the gateway still terminates TLS, applies authZ, and records telemetry as usual.

End-to-end sequence (simplified)

Client initialize → receives session id.
tools/list → client learns list_collections, execute_endpoint, etc.
Agent reasoning (or user prompt) selects an operation and builds arguments from endpoint_details.
tools/call with execute_endpoint → gateway routes to upstream like any other allowed request.
Logs and metrics record the call in the same pipelines as REST—see Observability.

For Management MCP, tool names and scopes differ—they mutate configuration and require operator identity (OIDC / service accounts per your setup).

Operational tips

Treat session ids like short-lived context—retry initialize on 401/400 from stale sessions.
Do not embed long-lived secrets in prompts; use server-side credential wallets where your client architecture allows it.
Load-test agents like any automation—tool loops can amplify QPS; see Rate limits that protect upstreams without punishing partners.

Where to go next

For AI agents — product framing and CTAs
Zerq Copilot — Management and Gateway Copilot modes using the same MCP surfaces
Give AI agents the same front door as your apps — audit story
Full reference documentation for your org lives in Zerq docs (Gateway MCP, Management MCP)—use the version matched to your release.

Summary: Discovery (tools/list) and execution (tools/call) over MCP map cleanly to published API operations when the gateway owns auth and policy. Zerq implements that path so agents do not need a second integration model.

Request an enterprise demo for a guided walkthrough on your environment.