STEP 01 / GENERATION

What generation produces

Each operation becomes a tool named after its operationId, described by its summary. Arguments are namespaced by where they travel, so a single flat object can never silently collide with another binding:

Path{id} is passed as bare id, then percent-encoded into the path template
Queryprefixed: a limit query parameter arrives as query_limit
Header and cookieprefixed the same way, and rejected if the configuration already sets that header
Request bodyarrives as one body object carrying the schema's own properties and required list

A spec whose input semantics are ambiguous or unresolvable is rejected outright rather than approximated, because a half-understood bridge is exactly how an agent ends up calling something its operator never meant to expose.

STEP 02 / CONFIGURE

Configure an upstream

Upstreams are declared by the operator, never by request input. The registry is a JSON array capped at sixteen entries:

export MCP_UPSTREAM_SERVERS_JSON='[{"id":"orders","transport":"openapi","baseUrl":"https://orders.example.test","specUrl":"https://orders.example.test/openapi.json","allowedTools":["listOrders","get*"],"readOnlyTools":["listOrders"]}]'

Replace specUrl with an inline spec object to run fully offline. Any non-empty registry automatically enables the external effect gate.

STEP 03 / POLICY

The allowlist decides what an agent can see

Matching is exact, a leading prefix*, or the single * wildcard. The default is not permissive:

Omitted or emptydenies every tool; the upstream is reachable but contributes nothing to the model surface
Exact nameadmits only that operation
Prefix starget* admits getOrder and leaves createOrder fenced
Read-only attestationonly names in readOnlyTools are marked side-effect free; everything else requires the external-effect path

STEP 04 / BOUNDARIES

What gets refused, in the gateway's own words

These are the literal outcomes, not paraphrases:

Non-HTTPS upstreamMCP upstream 'x' requires an https url.
Sixteenth extra entryMCP upstream registry exceeds the maximum of 16 servers.
Malformed registryMCP_UPSTREAM_SERVERS_JSON is not valid JSON.
Unresolvable inputsOpenAPI operation has unsupported, ambiguous, or unresolvable input semantics.
Blocked destinationOutbound request blocked by the gateway network policy.
Oversized responseOpenAPI bridge response exceeds the size limit.

The destination check runs before any transport is consulted, so a generated tool cannot be aimed at an internal address even when the caller controls nothing but argument values.

STEP 05 / SURFACE

Where the tools appear

GET /mcp/healthreadiness, or {"status":"disabled","upstreamCount":0} when no registry is configured
GET /mcp/toolstoolCount, tools, and servers, scoped to the authenticated identity
POST /mcp/callexecution routed through agent governance when it is enabled

Launch it the way the getting-started guide describes and add the environment variable above: Getting started covers the --publish 127.0.0.1:3100:3100 run against the published ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.8.0 image.

EVIDENCE BOUNDARY

How this page was checked

The generated tool names, the argument namespacing, the deny-by-default behaviour, the matching rules and each quoted error string were produced by executing the shipped modules at the v0.8.0 tag - apps/ai-gateway-service/src/mcpGateway/openApiRestBridge.ts and mcpGatewayConfig.ts - against a three-operation example spec with an injected transport. No network call was made, and no provider credential was used. The container run in the previous section is the documented one; it was not executed on the machine that wrote this page.

This is a Public Preview of self-hosted software. Nothing here claims production readiness, L5 autonomy, or AGI, and real providers are disabled by default.

See docs/reverse-mcp-governance.md for the full upstream contract