Expose a REST API as MCP tools

This guide configures an MCP proxy that reads an OpenAPI specification and generates one MCP tool per REST endpoint. Agents can then call those tools through the gateway without knowing the underlying HTTP API.

Agents that communicate over MCP cannot call REST APIs natively. The MCP proxy bridges that gap by translating each REST endpoint into an MCP tool, so your existing API becomes accessible to any MCP-compatible client.

Use this guide when you have a REST API with an OpenAPI 3.0 specification and want agents to call it through the gateway. If you need authentication, policies, or observability on the generated tools, an optional step attaches the proxy to an existing MCP surface.

Prerequisites

• A running Agent Gateway instance with the dashboard accessible.
• Power User or Administrator role on the gateway.
• The base URL and OpenAPI 3.0 specification (YAML format) of the REST API you want to expose.

Steps

Register the MCP proxy

In the dashboard, navigate to MCP Proxies and select Add MCP Proxy. This opens a three-step creation wizard.

Name

Fill in the proxy identity:

• Name: A descriptive label, for example Weather API.
• Description: Optional context for other gateway administrators.

Select Next.

Configure Connection

Set the routing and backend for the proxy:

• Listen Address (Host:Port): Select the address the proxy listens on.
• Path Prefix: Select the URL prefix for this proxy.
• Custom Endpoint Path: Enter the final path segment, for example weather-mcp.
• Base URL: The base URL of your REST API, for example https://api.weather.example.com.

The MCP Proxy Route preview shows the full address agents will use to call the proxy.

Select Next.

OpenAPI Specification

Paste your OpenAPI 3.0 specification in YAML format into the OpenAPI Spec (YAML) field.

Select Next. The gateway parses the specification and creates one MCP tool per API endpoint. The gateway shows a confirmation screen once the proxy is created.

Attach to an MCP surface (optional)

Skip this step if the standalone proxy route is sufficient and you do not need surface-level features.

Attach the proxy to an MCP surface when you need authentication, policies, or observability on top of the generated tools.

1. Open the MCP surface in the canvas editor.
2. Select the Managed Agent node to open its panel.
3. Under Endpoint, set Endpoint Type to via MCP Proxy.
4. From the MCP Proxy dropdown, select the proxy you created.
5. Select the Save changes button (the blue disk icon in the toolbar) or press Cmd+S / Ctrl+S.

The surface now serves all generated tools at its configured route with authentication, policies, and observability applied.

To create an MCP surface first, see MCP surface starter.

Configure tool access control (optional)

If the proxy is attached to an MCP surface, you can restrict which tools specific callers can invoke using per-tool Rego policies. See Control MCP tool access with per-tool policies.

Confirm

Send a tools/list request to the proxy route configured in Step 1.

curl -k -X POST https://GATEWAY_HOST/PROXY_PATH \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}'

The -k flag disables TLS certificate verification. Use this for local testing only. Remove it in production.

Replace PROXY_PATH with the full proxy route shown in the MCP Proxy Route field during Step 1, or the surface route if you completed Step 2.

Expected response: a tools array with one entry per REST API endpoint defined in your OpenAPI specification.

Update the OpenAPI specification

To update the specification after the proxy is created:

1. In the dashboard sidebar, select MCP Proxies, then select the proxy.
2. Open the REST API tab.
3. Edit the specification in the editor. Select Validate Specification to confirm the gateway can parse it. A green confirmation shows how many tools were found.
4. Select Save.

The proxy immediately serves the updated tool definitions. Any MCP surface attached to this proxy reflects the changes without reconfiguration.

Test tools with the MCP Sandbox

The proxy editor includes a built-in sandbox for testing tool calls directly from the dashboard.

1. Open the proxy in the proxy editor and select the Sandbox tab.
2. Select Connect & List Tools. The sandbox calls tools/list and lists all available tools.
3. Select a tool from the list.
4. Fill in the input parameters. Required parameters are marked.
5. Select Run Tool. The sandbox displays the raw JSON-RPC response.

Use the sandbox to verify your OpenAPI specification produces the expected tools before connecting an agent client.

Troubleshooting

Next steps

• MCP surface starter: Set up an MCP surface to serve the proxy’s tools with authentication and policies.
• MCP protocol: Understand how the gateway processes MCP traffic.