Handlers

MCP Server Handler

Applies to
Gatewayruntime for API, AI, and MCP gateways
Hosting
Managed EdgeManaged DedicatedSelf-Hosted

The MCP (Model Context Protocol) Server handler allows you to run a lightweight, stateless MCP server on your gateway that automatically transforms your API routes into MCP tools.

This enables your Zuplo Gateway to seamlessly serve external AI tools and agents through Model Context Protocol interactions by using your existing APIs, without needing to duplicate functionality or rebuild business logic in your backend.

Each MCP Server handler has a 1:1 relationship with a route. That means one route can host one server. A gateway may have any number of MCP servers.

A single MCP server may have many tools and prompts, where each tool interfaces with an API route in your gateway. You can compose multiple MCP servers on different routes to tailor MCP tools and prompts for each server's specific purpose.

The MCP Server Handler works by re-invoking configured routes on the gateway. It does not go back out to HTTP: it keeps requests within the gateway while still re-invoking the policy pipeline for your routes. This means that if you configure an MCP server with policies, routes with policies, and configure those routes as tools, the policy pipelines for both will be invoked. First the MCP server handler inbound policies, then the inbound policies for the tool's route, then the outbound policies for the tool's route, and finally, the outbound policies for the MCP server handler.

Setup via Portal

Open the Route Designer by navigating to the Code tab, then click routes.oas.json. For any route definition, select MCP Server from the Request Handlers drop-down. Set the method to POST.

Configure the handler with the following options:

  • Server Name (optional) - The name of the MCP server. AI MCP clients will read this name when they initialize with the server. If not set, the server advertises the default name Zuplo MCP Server.
  • Server Version (optional) - The version of your MCP server. AI MCP clients read this version when they initialize with the server and may make autonomous decisions based on the versioning of your MCP server and the instructions they've been given. If not set, the version defaults to 0.0.0.

Next, configure your routes to be transformed into MCP tools or prompts (see Configuration section below).

Setup via routes.oas.json

The MCP Server handler can be manually added to the routes.oas.json file with the following route configuration:

JSONCode
"paths": { "/mcp": { "x-zuplo-path": { "pathMode": "open-api" }, "post": { "summary": "MCP Server", "x-zuplo-route": { "corsPolicy": "none", "handler": { // The MCP Server Handler handler // and example options "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "name": "example-mcp-server", "version": "1.0.0", "debugMode": false, } }, "policies": { "inbound": [] } } } } }

Configuration

The MCP Server handler supports the following configuration options:

  • name (optional, default Zuplo MCP Server) - The name identifier of the MCP server.
  • version (optional, default 0.0.0) - The version of the MCP server.
  • debugMode (optional, default false) - Verbose logs on server startup, initialization, tool listing, and tool calls. NOT recommended for production environments.
  • operations - An array of operation references to register with the MCP server. Each operation can be a tool, prompt, or resource based on its x-zuplo-route.mcp configuration.
  • toolInputStyle (optional, default nested) - How generated tools advertise an operation's inputs. With nested, each input channel stays its own object (body, queryParams, pathParams, headers). With flat, a request body's properties and the operation's path, query, and header parameters all become top-level tool arguments. Flat tools accept the nested form too, so switching to flat doesn't break existing clients. This option sets the default for every tool on the server. A tool can override it with toolInputStyle in its route's x-zuplo-route.mcp block. Any value other than flat is read as nested. See Tool input schemas and the Flat tool input reference.
  • telemetry.captureToolCallContent (optional, default false) - Records tool call arguments and results on the tools/call trace span as gen_ai.tool.call.arguments and gen_ai.tool.call.result. Tool content often contains sensitive data, so turn this on only when your trace destination is allowed to store it. See MCP tracing.

Supported MCP protocol versions

The MCP Server handler accepts the MCP-Protocol-Version values 2024-10-07 through 2025-11-25 on every compatibility date. From compatibility date 2026-11-06, it also serves 2026-07-28. A request without the header is served as 2025-03-26. Any other value returns HTTP 400 with JSON-RPC error -32000, and so does 2026-07-28 on an earlier compatibility date. Some behavior depends on the version the client sends, such as refusing JSON-RPC batches from 2025-06-18 and returning invalid tool arguments as tool results from 2025-11-25. See JSON-RPC errors the handler returns.

MCP protocol 2026-07-28

From compatibility date 2026-11-06, the handler serves a request on revision 2026-07-28 when its MCP-Protocol-Version header names that revision. Requests on 2025-11-25 and earlier get the same answers as before, apart from the prompt message and batch changes the same date makes.

A 2026-07-28 client sees these differences:

  • Headers and envelope. Each request sends the MCP-Protocol-Version, Mcp-Method, and, for a tool, prompt, or resource, Mcp-Name headers, plus the per-request _meta envelope in params. A request that names 2026-07-28 only in _meta, without the MCP-Protocol-Version header, returns HTTP 400 with -32020, because the header is required. A request whose _meta names 2025-11-25 or an earlier revision the handler serves, without a 2026-07-28 header, is served on that earlier revision.
  • Discovery instead of a handshake. The client calls server/discover instead of initialize. The reply lists supportedVersions (2026-07-28, then 2025-11-25 through 2024-10-07), the server's capabilities, and its name and version in _meta["io.modelcontextprotocol/serverInfo"]. A client can negotiate down to an earlier revision, which it opens with initialize.
  • Removed methods. initialize, ping, logging/setLevel, resources/subscribe, and resources/unsubscribe return HTTP 404 with JSON-RPC error -32601.
  • Result fields. Every result carries resultType: "complete" and the server's name and version in _meta["io.modelcontextprotocol/serverInfo"]. The server/discover, tools/list, prompts/list, resources/list, resources/templates/list, and resources/read results also carry ttlMs: 0 and cacheScope: "private", so a client treats them as stale right away and doesn't share them with another caller.
  • Errors. A missing envelope, headers that disagree with the body, and an unsupported revision return HTTP 400 with -32602, -32020, and -32022. An unknown tool, prompt, or resource returns -32602 with the name or URI in the message, such as Tool nope not found. 2026-07-28 has no JSON-RPC batches, so a batch, like a posted JSON-RPC response, returns HTTP 400 with -32600. The 406 for an Accept header that doesn't allow application/json and the 415 for a non-JSON Content-Type also carry -32600. See JSON-RPC errors on 2026-07-28.

The handler doesn't serve these 2026-07-28 features: tools that ask the client for input (input_required results, elicitation, sampling, and roots), subscriptions/listen notifications, logging, tasks, and per-caller caching hints.

If a hook or policy answers or changes a tools/call request before the handler runs it, update it for 2026-07-28 clients:

  • A response it returns itself must include resultType: "complete" in result when the request's MCP-Protocol-Version header is 2026-07-28, or the client rejects it.
  • If it rewrites the tool name in params.name, it must also set the Mcp-Name header to the new name, or the handler returns HTTP 400 with -32020.

The MCP Gateway also supports 2026-07-28 from compatibility date 2026-11-06.

MCP 2025-06-18 Global Options

These options are part of the new MCP specification (2025-06-18). Some MCP clients may not yet support these features and output schemas may not be considered valid by various clients given MCP has not yet adopted an exact JSON schema dialect. If you experience compatibility issues with your MCP client, ensure your outputSchema is a valid type: object JSON Schema and structuredContent is also of type: object.

  • includeOutputSchema (optional, default: false) - Whether to include output schema from the route's OpenAPI response schema. When true, the schema from successful responses (2xx) will be used as outputSchema for MCP tools.
  • includeStructuredContent (optional, default: false) - Whether to include structured content in responses. When true, response JSON will be parsed and included as structuredContent. When false, only text content will be returned.

Enable includeOutputSchema and includeStructuredContent together. Turning on includeOutputSchema alone makes the server advertise an output schema while returning only text content, which causes MCP clients to fail tool calls with Tool call failed: 500. See Troubleshooting the MCP Server Handler for how to diagnose and fix this.

Operations

Configure MCP tools, prompts, and resources using the operations configuration. Specify OpenAPI files and the exact operation IDs you want to expose:

JSONCode
"paths": { "/mcp": { "post": { "x-zuplo-route": { "handler": { "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "name": "My MCP Server", "version": "1.0.0", "operations": [ { "file": "./config/weather.oas.json", "id": "getCurrentWeather" }, { "file": "./config/todos.oas.json", "id": "createTodo" } ] } } } } } }
  • file: Path to an OpenAPI JSON spec file (relative to the project root)
  • id: The specific operation ID to include from the targeted file

This approach provides explicit control over exactly which API operations become MCP tools, prompts, or resources.

Deprecated Configurations

The files, prompts, and resources configuration options are deprecated and will be removed in a future version. Please migrate to the operations configuration option described above.

Legacy Configuration Options (Deprecated)

Prior to operations, specific configuration arrays were used:

  • files: For tools
  • prompts: For prompts
  • resources: For resources
JSONCode
"post": { "operationId": "mcp-server", "x-zuplo-route": { "handler": { "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "files": [ { "path": "./config/weather.oas.json", "operationIds": [ "getCurrentWeather" ] } ], "prompts": [ { "path": "./config/weather.oas.json", "operationIds": [ "weatherPrompt" ] } ] } } }

Please migrate these to the unified operations array.

MCP Tools

Tools are the main way that AI agents can discover capabilities from MCP servers. They are flexible, lite weight ways to execute some functionality, query some data, or perform an action on the user's behalf.

Routes configured as MCP tools may include the x-zuplo-route.mcp extension with type: "tool" in their OpenAPI definition. By default, without the x-zuplo-route.mcp configuration, the MCP server handler will assume the provided operation is a "tool". See MCP Server Tools for detailed documentation.

Custom MCP Tools

Create custom tools as routes with full programmatic control using dedicated OpenAPI specifications and custom handler functions.

This approach provides maximum flexibility for complex workflows. See MCP Server Custom Tools for detailed documentation.

MCP Prompts

In addition to tools, MCP servers can expose prompts - reusable, parameterized prompt templates that AI clients can request and execute. Configure prompts using the operations array in your MCP server options, just like tools.

Routes configured as MCP prompts must include the x-zuplo-route.mcp extension with type: "prompt" in their OpenAPI definition. See MCP Server Prompts for detailed documentation.

MCP Resources

MCP servers can also expose resources - static read-only content like documentation, configuration files, or any other data an AI system might need. Like tools and prompts, configure resources using the operations array in your MCP server options.

Routes configured as MCP resources must use the GET method and must include the x-zuplo-route.mcp extension with type: "resource" in their OpenAPI definition.

See MCP Server Resources for detailed documentation.

Route x-zuplo-route.mcp configuration

You can customize individual tools, prompts, and resources using the x-zuplo-route.mcp property in your OpenAPI definition. This allows you to define the type of MCP capability and provide specific metadata.

JSONCode
"paths": { "/weather/current": { "get": { "operationId": "getCurrentWeather", "summary": "Get current weather", "x-zuplo-route": { "handler": { ... }, "mcp": { "type": "tool", "name": "get_current_weather", "description": "Retrieve current weather conditions for a specified location", "enabled": true } } } }, "/prompts/greeting": { "post": { "operationId": "greeting-prompt", "x-zuplo-route": { "handler": { ... }, "mcp": { "type": "prompt", "name": "greeting_generator", "description": "Generate a personalized greeting" } } } } }

Common options:

  • type: The type of MCP capability (tool, prompt, resource, or graphql). Defaults to tool if not specified.
  • name: Override the name shown to AI systems (defaults to operationId)
  • description: Override the description for AI consumption (defaults to route description/summary). The default uses at most the first 350 characters of the route description, while an override has no length limit.
  • enabled: Whether this operation should be available in the MCP server.

See the respective tools, prompts and resources documentation for type-specific options.

Authentication

OAuth Authentication

The MCP Protocol natively supports OAuth authentication to enable MCP Clients to authenticate and authorize themselves when calling tools. For more information, see the official MCP Authentication documentation.

Zuplo allows you to configure any of the built-in OAuth policies (like Auth0, Okta, etc.) on the MCP Server route to secure it. To enable OAuth authentication, you will need to have an OAuth Authorization server configured. Specifically, the OAuth Authorization server will need to support the following things:

  1. (Optional but recommended) OAuth 2.0 Dynamic Client Registration
  2. Authorization Code Grant with PKCE
  3. Refresh Tokens

For an example of a basic configuration of an Authorization Server with Auth0, see: Setting up Auth0 as an Authentication Server for MCP OAuth Authentication.

Once you have configured your authorization server, you can do the following to enable OAuth authentication on your MCP Server:

  1. Create an OAuth policy on your MCP Server route. This policy will need to have the option "oAuthResourceMetadataEnabled": true, for example:

    JSONCode
    { "name": "mcp-oauth-inbound", "policyType": "oauth-inbound", "handler": { "export": "Auth0JwtInboundPolicy", "module": "$import(@zuplo/runtime)", "options": { "auth0Domain": "my-auth0-domain.us.auth0.com", "audience": "https://my-mcp-audience", "oAuthResourceMetadataEnabled": true } } }

    In this example, the audience should be the identifier of the Auth0 API you want your MCP Server to be protected by. For more information on configuring OAuth JWT policies, see the OAuth Policy docs.

  2. Add the OAuth policy to the MCP Server route. For example:

    JSONCode
    "paths": { "/mcp": { "post": { "x-zuplo-route": { // etc. etc. // other properties and route handlers for MCP "policies": { "inbound": [ "mcp-oauth-inbound" ] } } } } }
  3. Add the OAuthProtectedResourcePlugin to your runtimeInit function in the zuplo.runtime.ts file:

    TypeScriptCode
    import { OAuthProtectedResourcePlugin } from "@zuplo/runtime"; export function runtimeInit(runtime: RuntimeExtensions) { runtime.addPlugin( new OAuthProtectedResourcePlugin({ authorizationServers: ["https://your-auth0-domain.us.auth0.com"], resourceName: "My MCP OAuth Resource", scopesSupported: ["mcp:access", "offline_access"], }), ); }

    scopesSupported lists the scopes MCP clients should request. The plugin emits it as scopes_supported in the metadata document, and the OAuth policy adds it as the scope parameter of its 401 WWW-Authenticate challenge. Without it, some clients request every scope the authorization server advertises. Replace the example values with the scopes your authorization server defines for this resource.

    See the OAuth Protected Resource Plugin docs for all options and Advertising supported scopes for how clients pick scopes.

API Key Auth

An MCP server on Zuplo can be configured to use an API key from a query parameter using the Query Parameter to Header Policy.

Currently, API keys aren't supported directly by MCP. But using an API key via query params transformed through your Zuplo gateway is a great way to get up and running quickly with an MCP server.

Configure the policy to expect a query param and inject it as an Auth header:

JSONCode
{ "policies": [ { "name": "mcp-query-param-to-header-inbound", "policyType": "query-param-to-header-inbound", "handler": { "export": "QueryParamToHeaderInboundPolicy", "module": "$import(@zuplo/runtime)", "options": { "queryParam": "apiKey", "headerName": "Authorization", "headerValue": "Bearer {value}" } } } // etc. etc. other policies, your API key policy ] }

Then, to secure your MCP endpoint, add the "query param to header" policy before your API key policy:

JSONCode
{ "paths": { "/mcp": { "post": { "x-zuplo-route": { // etc. etc. // other properties and route handlers for MCP "policies": { "inbound": [ "mcp-query-param-to-header-inbound", "api-key-auth-inbound" ] } } } } } }

This will effectively transform the query param into an Authorization: Bearer header and pass those through to other routes on your gateway.

Then, when using MCP clients, simply add your API key as a query param! For example, in Cursor:

JSONCode
{ "mcpServers": { "my-zuplo-mcp-server": { "url": "https://my-server.zuplo.com/mcp?apiKey=123abc" } } }

Keep REST routes private

Every operation an MCP server exposes is still a route on your gateway, and clients can reach that route directly over HTTP. To make the routes reachable only through the MCP server, add the Internal Only policy to every route the server exposes.

The MCP Server handler calls each route with context.invokeRoute, which the Internal Only policy accepts. The policy rejects every request that arrives over the network. Set status to 404 so a direct call gets the same response as a route that doesn't exist:

JSONconfig/policies.json
{ "name": "internal-only-inbound", "policyType": "internal-only-inbound", "handler": { "export": "InternalOnlyInboundPolicy", "module": "$import(@zuplo/runtime)", "options": { "status": 404 } } }

Put the policy first in the inbound policies of each route, so nothing else runs for a rejected request:

JSONconfig/routes.oas.json
"/orders/{orderId}": { "get": { "operationId": "get-order", "x-internal": true, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-zuplo-route": { "corsPolicy": "none", "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)", "options": { "baseUrl": "https://orders.example.com" } }, "policies": { "inbound": ["internal-only-inbound"] } } } }

When you hide a route:

  • Authenticate callers on the MCP server route. The Internal Only policy checks where a request comes from, not who sent it. The MCP server forwards the client's request headers to each route, so a route can keep its own authentication policy after this one.
  • Set corsPolicy to none. Preflight OPTIONS requests skip inbound policies, so a route with a CORS policy still answers them.
  • Mark the route x-internal to keep it out of your developer portal.
  • A custom not-found handler answers paths that don't exist with your own response, so a hidden route's 404 no longer matches it.

Testing

MCP Inspector

Use the MCP Inspector, a developer focused tool for building MCP servers, to quickly and easily test out your MCP server:

TerminalCode
npx @modelcontextprotocol/inspector

By default, this will start a local MCP proxy and web app that you can use on localhost to connect to your server, list tools, call tools, view message history, and more.

To connect to your remote Zuplo MCP server in the Inspector UI:

  1. Set the Transport Type to "Streamable HTTP"
  2. Set the URL to your Zuplo gateway with the route used by the MCP Server Handler (that is, https://my-gateway.zuplo.dev/mcp)
  3. If you have configured OAuth authentication, you will need to login using the OAuth flow using the Open Auth Settings button.
  4. Hit Connect.

Curl

For more fine grained debugging, utilize MCP JSON RPC 2.0 messages directly with curl. There are lots of different interactions and message flows supported by MCP, but some useful ones include:

Ping

To send a simple "ping" message, which can be useful for testing availability of your MCP server:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "0", "method": "ping" }'

List tools

To see what tools a server has registered:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "0", "method": "tools/list" }'

List prompts

To see what prompts a server has available:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "0", "method": "prompts/list" }'

List resources

To see what resources a server has available:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "0", "method": "resources/list" }'

Call tool

To manually invoke a tool by name:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": { "name": "my_tool", "arguments": {} } }'

For more complex tools, you'll need to provide the schema compliant arguments. Note the inputSchema for the tool from tools/list to appropriately craft the arguments.

Get prompt

To execute a prompt with parameters:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "prompts/get", "params": { "name": "my_prompt", "arguments": { "param1": "value1" } } }'

For prompts with parameters, provide the required arguments object based on the prompt's schema from prompts/list.

Read resource

To read a resource by its URI:

TerminalCode
curl https://my-gateway.zuplo.dev/mcp \ -X POST \ -H 'accept: application/json, text/event-stream' \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "resources/read", "params": { "uri": "mcp://resources/my_resource" } }'

Use the URI from resources/list to specify which resource to read.

Read more about how calling tools works in the Model Context Protocol server specification.

OAuth Testing

If you have configured OAuth authentication for your MCP Server, you can use the MCP Inspector to test the OAuth flow.

Hit the Open Auth Settings button in the Inspector UI to start the OAuth flow. When first setting up the OAuth flow, it's recommended to use the Guided OAuth Flow which you will see when you open the OAuth settings. This will allow you to debug the flow step by step.

The OAuth flow involves the following steps, as shown in the MCP inspector guided auth flow. After you've checked each step, click the Continue button in the MCP Inspector UI to move to the next step.

  1. Metadata Discovery: The MCP Inspector will make a request to the .well-known/oauth-protected-resource endpoint to learn about the OAuth configuration. The MCP Inspector will then make a request to the Authorization server which you configured in the OAuthProtectedResourcePlugin, which will return the metadata it needs to continue with the OAuth flow.

    If you see errors in this part, check that you have correctly added the OAuthProtectedResourcePlugin to your zuplo.runtime.ts file, and that you have correctly configured the authorizationServers value to be the canonical URL of your Authorization server, and registered an OAuth policy to the route of your MCP server.

    If the authorization server later rejects the authorization request with a scope error (Okta reports illegal_scope_combination), the client built its scope list from the authorization server's metadata. Set scopesSupported on the plugin so the client requests only those scopes. See Advertising supported scopes.

  2. Client Registration: The MCP Inspector will try to use Dynamic Client Registration to register a new client with the Authorization server. Note that not all MCP Clients require this, however at this time, the MCP Inspector does. You will need to enable Dynamic Client Registration on your Authorization server if you want to test the full flow through the MCP Inspector.

    If you see errors in this step, check that you have enabled Dynamic Client Registration on your Authorization server.

  3. Preparing Authorization: The MCP Inspector will then redirect the user to the authorization server to login and authorize the MCP Client. Click the redirect link in the Authorization URL section to be prompted to login. After logging in, you will be given a code to copy in to the next step.

  4. Request Authorization and acquire authorization code: Take the copied code from the last step and paste it in to the MCP Inspector and input it into the box.

  5. Token Request: The MCP Inspector will do PKCE and make a request to the token endpoint of your Authorization server to exchange the authorization code for an access token. This is attached as the Authorization header when calling your MCP server, typically as a Bearer token.

  6. Authentication Complete: You should now see a success message in the MCP Inspector. You can now hit the Connect button to connect to your MCP server.

If you see errors in the flow in steps 2-6, check that you have correctly configured your Authorization server to support the OAuth 2.0 Authorization Code Grant with PKCE and Refresh Tokens.

MCP Client

By connecting to an LLM enabled MCP Client, you can test the true end to end experience.

Many clients (like OpenAI, Claude Desktop, or Cursor) let you define the remote server URL and the name. For example, in Cursor, you can add your MCP server like so:

JSONCode
{ "mcpServers": { "my-custom-mcp-server": { "url": "https://my-gateway.zuplo.dev/mcp" } } }
Last modified on