MCP surface starter

Use this guide when you want AI agents to call MCP tools through a governed access point, so every request is subject to identity, scope, and observability rather than reaching the MCP server directly.

An MCP surface is that access point: it defines the inbound route from external callers to your managed agent and, optionally, routes outbound calls from your agent to an external MCP server through a transit point.

This guide walks through creating the surface, configuring both routes, and confirming the setup works end to end.

Prerequisites

• You are logged in to the Agent Gateway dashboard.
• You have permission to create surfaces.
• A publicly accessible MCP server for your managed agent. The gateway must be able to reach this endpoint. If your server runs locally, use a tunnelling tool to expose it over a public URL. For production use, deploy your MCP server to a stable, publicly reachable endpoint.
• (Optional, for outbound routing) A separate publicly accessible MCP server to receive outbound calls through the transit point.

Steps

Add a new surface and select a template

1. Open Surfaces in the dashboard.
2. Select Add Surface.
3. In Start a new surface, select the MCP Surface Starter template.
4. Update the generated Name, such as mcp_surface_1, in the Surface tab if needed.

The canvas opens with three elements: a Surface container (blue box), a Managed Agent node, and an Access Point node. Elements with red outlines still require configuration. Additional templates are available in the Templates view after the canvas opens.

Tip: Select the auto-layout icon in the toolbar (tooltip: Auto-layout (⌘L / Ctrl+L)) to realign the canvas at any time. Select the undo icon (tooltip: Undo (⌘Z / Ctrl+Z)) to revert a change.

Configure the Managed Agent

1. Select the Managed Agent node.
2. Set Target Endpoint URL to the MCP server URL that should receive forwarded traffic.

Note

If your managed agent is a REST API with an OpenAPI specification rather than a native MCP server, you can generate an MCP-compatible endpoint from it using an MCP proxy. See Expose a REST API as MCP tools.

If required fields are incomplete, the red outline remains and the Elements tab lists what is still missing.

Configure the Access Point

The MCP Surface Starter template pre-configures the Access Point node with defaults for your deployment. Select the Access Point node to review or update the Entry point URL: the URL where external callers reach your surface.

The URL is composed from the gateway’s address and two fields in the Routing section: Surface Prefix and Custom Path. The full URL is shown in the Entry point URL banner at the top of the panel and on the canvas.

The route part of the Entry point URL, the surface prefix and custom path, is also the base path for any transit point you add in Step 4.

Add a transit point for outbound MCP calls (optional)

Skip this section if you only need inbound routing from external callers to your managed agent.

1. From the canvas palette, drag Transit Point (MCP) from the Transit Points section onto the canvas. The new node connects to the Managed Agent automatically.
2. Fill in the following fields in the transit point panel:

Field	Value
Name	mcp-weather
Endpoint Type	Direct URL
Target Endpoint	The public URL of your MCP server.
Surface Prefix	Accept the default outbound prefix, for example outbound → routes.
Custom Path	mcp-weather. The Listener URL banner at the top of the panel shows the full URL your managed agent calls, for example https://<GATEWAY_HOST>/outbound/routes/mcp-weather.

Configuration notes:

• The alias shown is derived automatically from the name you enter.

Confirm

Open the Elements tab and confirm that all required fields are complete. No red outlines should remain on any surface element. You can also open the Config tab to inspect the configuration of your surface.

Once the Elements tab shows all fields as complete, save the surface. In create mode, select the green checkmark button in the toolbar (tooltip: Create surface). In edit mode, select the disk icon button in the toolbar (tooltip: Save changes).

The surface is now live and the gateway begins routing traffic. Connect an MCP-compatible client to the URL shown in the Entry point URL banner to confirm end-to-end routing.

Default outbound route (no custom path set):

https://<GATEWAY_HOST>/outgoing/<SURFACE_ROUTE>/<TRANSIT_ALIAS>/<OPTIONAL_PATH>

Example:

https://<GATEWAY_HOST>/outgoing/<your-surface-route>/mcp-weather

Custom outbound route (custom path set): the surface prefix followed by the custom path, as shown in the transit point’s Listener URL banner.

https://<GATEWAY_HOST>/<SURFACE_PREFIX>/<CUSTOM_PATH>/<OPTIONAL_PATH>

Save as a reusable template (optional)

1. Select the Surface tab in the left sidebar.
2. Select Save Surface as Template….
3. Fill in the template metadata: name, details, description, and priority in the template list.
4. Save the template.

Your template is then available in future surface creation flows alongside the prebuilt templates.

Troubleshooting

Next steps

• Control MCP tool access with per-tool policies: restrict which tools the surface exposes using per-tool policies.
• Expose a REST API as MCP tools: use an MCP proxy to convert a REST API into the surface’s managed agent endpoint.