Skip to main content
An instance combines the tools of every Model Context Protocol (MCP) server and REST API added to it into one MCP server at {gateway_url}/mcp. The agent connects one MCP client to the gateway instead of one to each server. The gateway routes each tool request to the server or API that owns the tool, and authenticates to it with that target’s own credentials. It serves the MCP servers’ prompts and resources the same way.

​
Set Up

​
MCP Servers

POST /v2/agent_gateways/{id}/mcp_servers adds a server by its MCP endpoint. This one runs inside the user’s network, behind tunnel hosts Preview, and the gateway sends it an API key:

​
APIs

POST /v2/agent_gateways/{id}/apis adds a REST API by the URL of its OpenAPI description, in JSON. Each operation in the description becomes one tool. When the agent invokes the tool, the gateway sends the operation’s HTTP request to the API itself, with no MCP server in between. This public API needs no auth:
The gateway reads OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0. Without a base_url, it takes the first entry in the description’s servers. The gateway reaches an MCP server or API across the instance’s Network, so either can stay off the internet.

​
Outbound Authentication

Outbound authentication is not a resource of its own. Each MCP server and API holds its method and the credentials themselves in auth, and the gateway authenticates to it with them on every request. Responses return only auth.type. auth.type picks the method: OAuth authorization code and OAuth token exchange are Planned.

​
Settings

Each MCP server and API has:
  • A name, which prefixes its tools. A name holds up to 100 letters, digits, _, and ., and is unique on the instance, regardless of case, across MCP servers and APIs.
  • Its address. An MCP server has a url and a transport, Streamable HTTP (http, the default) or Server-Sent Events (sse). An API has a spec_url and a base_url.
  • An auth, its outbound authentication method.
  • tools, the tools it exposes to every key, by name. [] exposes every tool.
  • static_headers, sent on every request, and forwarded_headers, copied from the agent’s request by name.
  • open_to_every_key, which opens it to every key on the instance. Otherwise, only the keys granted it may use it.
Only the name and the url or spec_url are required.

​
Operations as Tools

The gateway makes one tool from each get, post, put, patch, and delete operation in an API’s description: The operation findPetsByStatus on the API petstore is the tool petstore-findpetsbystatus. Header and cookie parameters are not sent to the API. A request body defined by a $ref reaches the agent as an object with no properties.

​
Changes

PATCH /v2/agent_gateways/{id}/mcp_servers/{server_id} changes a server’s settings, and PATCH /v2/agent_gateways/{id}/apis/{api_id} changes an API’s. An update replaces auth whole, and {"type": "none"} removes the credential. DELETE on the same paths removes the server or API.

​
Use

​
Connections

Any MCP client connects to {gateway_url}/mcp over Streamable HTTP, at protocol versions 2024-11-05 through 2025-11-25. The client presents its key as a bearer token, Authorization: Bearer <key>.

​
Tool Names

Every tool’s name starts with its server’s or API’s name and a hyphen. The tool get_order on the server orders is orders-get_order:
Output
Prompts carry the same prefix, so names stay unique across servers.

​
Server Scoping

{gateway_url}/mcp/{server} serves only that server’s tools, still prefixed. A comma-separated list, such as {gateway_url}/mcp/github,jira, serves several. The x-mcp-servers header narrows {gateway_url}/mcp the same way, with a comma-separated list of server names. A path or header narrows what the agent sees. It never adds a server the agent has no permission to use.

​
Results

An API tool’s result is the API’s response body when the response is in the 2xx range. Any other response is an error result that names the HTTP status, without the API’s response body:
Output
With tool search Preview on for a key, tools/list returns four search tools in place of the full catalog. Two of them reach MCP tools:
  • mcp_tool_search takes a query and an optional top_k, 5 by default. It returns the matching tools, each with its name, description, and input schema.
  • mcp_tool_call takes a tool_name and its arguments, and invokes that tool.
The other two, agent_search and skill_search, find agents and skills by query. Matching is by keyword. A tool scores a point for each word of the query found in its name or description, and a tool that scores nothing is left out. With an embedding model set on the instance, matching is by meaning instead. Search covers only the tools the key may use, and mcp_tool_call applies the same tool permissions as a direct request.