Copy page

MCP Server

MCP Server Tools

Applies to

Gatewayruntime for API, AI, and MCP gateways

Hosting

Managed EdgeManaged DedicatedSelf-Hosted

The MCP (Model Context Protocol) Server handler supports tools, enabling you to expose your API routes as executable functions that AI clients can call to perform actions or retrieve data.

Tools are the core building block of MCP servers, allowing AI systems to interact with your services and discover capabilities through your Zuplo gateway.

Overview

Zuplo's MCP tools work by automatically transforming your API routes into MCP tool definitions. When an AI client calls a tool, the MCP server invokes the corresponding route handler in your gateway.

This means any existing API route can be instantly turned into an MCP tool with minimal configuration.

Configuration

Route Configuration

Configure a route in your OpenAPI doc:

Code
{
  "/weather/current": {
    "get": {
      "operationId": "getCurrentWeather",
      "summary": "Get current weather",
      "description": "Retrieve current weather conditions for a specified location",
      "parameters": [
        {
          "name": "location",
          "in": "query",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "export": "default",
          "module": "$import(./modules/weather)"
        },
        "mcp": {
          "type": "tool",
          "name": "get_current_weather",
          "description": "Retrieve current weather conditions for a specified location"
        }
      }
    }
  }
}

To provide MCP specific metadata for the tool, use the mcp property within x-zuplo-route:

The x-zuplo-route.mcp configuration for tools supports:

• type (string: optional, defaults to tool) - Set to "tool" to denote this operation is an MCP tool.
• name (string: optional) - The identifier for the MCP tool. Defaults to the operation's operationId. If the operationId is not set, falls back to an auto-generated name.
• description (string: optional) - Description of what the tool does. Falls back to the operation's description or summary. If the route's description or summary fields are not set, falls back to an auto-generated description. The fallback uses at most the first 350 characters of the operation's description, followed by .... Set description here when the tool needs a longer description: this field has no length limit.
• enabled (boolean: optional) - Whether this tool is enabled. Defaults to true.
• includeOutputSchema (boolean: optional) - Whether to advertise the route's successful (2xx) response schema as the tool's outputSchema. Overrides the handler's includeOutputSchema option for this tool.
• includeStructuredContent (boolean: optional) - Whether to return the response JSON as structuredContent. Overrides the handler's includeStructuredContent option for this tool. Turns on automatically when includeOutputSchema is true.
• toolInputStyle (string: optional) - "flat" or "nested". How this tool advertises the operation's inputs. Overrides the handler's toolInputStyle option for this tool. See Set the input style per tool.
• annotations (object: optional) - An object containing tool annotations:
  • title (string: optional) - A human-readable title for the tool, often used by clients.
  • readOnlyHint (boolean: optional) - Hint that the tool is read-only.
  • destructiveHint (boolean: optional) - Hint that the tool has mutating side effects.
  • idempotentHint (boolean: optional) - Hint that the tool is idempotent.
  • openWorldHint (boolean: optional) - Hint that the tool operates in an open-world context of external entities (like web-search).
• _meta (object: optional) - An object containing any arbitrary metadata.

The route handler for your tool can be any standard Zuplo request handler like the URL Forwarder or the Redirect handler or a custom function module. The route receives the request triggered by the MCP tool call within the gateway and returns a response that will be passed back through the MCP server to the AI client.

MCP Server Handler Configuration

Add tool configuration to your MCP Server handler options using the operations array:

Code
{
  "paths": {
    "/mcp": {
      "post": {
        "x-zuplo-route": {
          "handler": {
            "export": "mcpServerHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "name": "example-mcp-server",
              "version": "1.0.0",
              "operations": [
                {
                  "file": "./config/routes.oas.json",
                  "id": "getCurrentWeather"
                }
              ]
            }
          }
        }
      }
    }
  }
}

See further details in the MCP Server Handler documentation.

Tool input schemas

Zuplo derives each tool's inputSchema from the operation's OpenAPI definition. The toolInputStyle setting decides its shape:

• nested (default) - Each input channel the operation declares is its own object argument: pathParams, queryParams, body, or headers.
• flat - The operation's path, query, and header parameters and the request body's properties all become top-level tool arguments.

Some models, particularly less capable ones, send a body's fields at the top level even when the tool advertises them under body. Against a nested schema, that first call fails validation and the model retries with the wrapper, which costs a round trip on every call. Flat input removes the wrapper. MCP doesn't require either shape, and capable models generally follow whatever schema a tool advertises, so flat is opt-in.

Set toolInputStyle in the handler options to choose the style for every tool on the server:

Code
"options": {
  "toolInputStyle": "flat",
  "operations": [{ "file": "./config/routes.oas.json", "id": "searchProducts" }]
}

To give one tool a different style, see Set the input style per tool. The default is nested on every compatibility date.

For example, POST /stores/{storeId}/search declares a path parameter storeId, an optional query parameter limit, a required header x-tenant, and a JSON body with a required query and an optional sort. The two styles advertise these schemas (each property's schema shortened):

nested
{
  "type": "object",
  "properties": {
    "pathParams": {
      "type": "object",
      "properties": { "storeId": {} },
      "required": ["storeId"]
    },
    "queryParams": {
      "type": "object",
      "properties": { "limit": {} },
      "required": []
    },
    "body": {
      "type": "object",
      "properties": { "query": {}, "sort": {} },
      "required": ["query"]
    },
    "headers": {
      "type": "object",
      "properties": { "x-tenant": {} },
      "required": ["x-tenant"]
    }
  },
  "required": ["pathParams", "queryParams", "body", "headers"]
}

flat
{
  "type": "object",
  "properties": {
    "storeId": {},
    "limit": {},
    "query": {},
    "sort": {},
    "x-tenant": {}
  },
  "required": ["storeId", "query", "x-tenant"]
}

A flat call passes every argument at the top level:

Code
{
  "name": "searchProducts",
  "arguments": {
    "storeId": "s1",
    "limit": 10,
    "query": "hoodie",
    "x-tenant": "acme"
  }
}

The gateway routes each argument back to the channel that declared it, so the route receives POST /stores/s1/search?limit=10 with the header x-tenant: acme and the body {"query":"hoodie"}. That's the same request the equivalent nested call produces.

For the full mapping rules, every case that keeps a tool nested, and the log and build messages, see Flat tool input.

Undeclared arguments

Your own OpenAPI schema decides whether an argument the tool doesn't declare is rejected:

• The schema sets additionalProperties: false. The tool's flat schema is closed too, and an undeclared argument fails as an invalid-arguments error.
• The schema omits additionalProperties. JSON Schema permits extras, so the tool accepts the argument and forwards it in the request body.

Set additionalProperties: false on a request body schema when you want the gateway to reject fields a model invented rather than pass them upstream.

An argument routes to a request header only when a header parameter declares that exact name. An undeclared argument never becomes an upstream header.

When arguments stay nested

Some operations can't be flattened without changing what the tool accepts:

• Two channels declare the same name. A limit query parameter alongside a limit body field, for example. Rename one of them to get flat arguments.
• The request body isn't a plain object. An array, a string, or a body built from oneOf or anyOf has no property names to hoist. Neither does one that constrains the object as a whole, such as with minProperties or patternProperties.

From compatibility date 2026-11-06, a tool whose toolInputStyle is flat and that can't be fully flattened fails the build. The error names the tool, the operation, and the cause. Change the schema so it flattens, or set "toolInputStyle": "nested" on that tool. A root allOf of plain object schemas and a dependentRequired that names only body properties also flatten from this date.

On earlier compatibility dates, those tools keep part or all of the nested shape even when toolInputStyle is flat, and the MCP server logs the reason when it registers the tool. With a name collision, the whole schema stays nested and the server logs a warning. With a body that isn't a plain object, the parameters still flatten and the body keeps its own body argument. Enable debugMode to see which tools this applies to.

See Flat tool input for the full list of body shapes and the exact build errors.

The channel names are body, queryParams, pathParams, and headers. Only the channels the operation declares appear.

Calling a tool with nested arguments

Flat tools also accept the nested form, so a client written against the nested schema keeps working:

Code
{
  "name": "searchProducts",
  "arguments": {
    "pathParams": { "storeId": "s1" },
    "queryParams": { "limit": 10 },
    "body": { "query": "hoodie" },
    "headers": { "x-tenant": "acme" }
  }
}

Send flat arguments in new clients — that's what a flat tool advertises. A call that mixes the two forms is read as flat.

Set the input style per tool

Set toolInputStyle in a route's x-zuplo-route.mcp block to give that tool a different input style from the rest of the server:

Code
"x-zuplo-route": {
  "mcp": { "type": "tool", "toolInputStyle": "flat" }
}

Each tool uses the first value it finds:

1. The tool's own toolInputStyle.
2. The handler's toolInputStyle option.
3. nested.

The override works in either direction: a flat tool on a nested server, or a nested tool on a flat server. Use it to add tools with flat inputs to an existing MCP server without changing the schema its current tools advertise, and without creating a second MCP route. Flat tools still accept nested arguments, so switching one tool to flat doesn't break existing callers. Only that tool's advertised inputSchema changes.

toolInputStyle accepts only "flat" or "nested". The build rejects any other value in x-zuplo-route.mcp. On the handler, any other value is read as nested without an error.

If your MCP server still uses the deprecated files option, set toolInputStyle in the operation's x-zuplo-mcp-tool extension instead. The MCP server checks that value when it registers the tool and throws an error that names the operation:

Code
MCP tool configuration error: invalid toolInputStyle "Flat" on operation "createOrder". Use "flat" or "nested".

From compatibility date 2026-11-06, toolInputStyle must be a literal value on the handler and on every tool. A $env(...) value fails the build.

Parameter serialization

From compatibility date 2026-11-06, the MCP Server handler writes path, query, and header arguments into the request using each parameter's OpenAPI style, explode, allowReserved, and content. Before that date it uses one fixed encoding per location, so a route that declares a style such as deepObject, pipeDelimited, label, or matrix may receive a value it can't parse.

Code
Query parameter  rgb: { style: deepObject, explode: true }
Arguments        { "rgb": { "R": 100, "G": 200, "B": 150 } }

Before 2026-11-06   GET /swatches?rgb=%7B%22R%22%3A100%2C%22G%22%3A200%2C%22B%22%3A150%7D
From 2026-11-06     GET /swatches?rgb[R]=100&rgb[G]=200&rgb[B]=150

Tool names follow the same rule set from that date: names that don't match the MCP tool naming rule are rewritten. See Build warning: tool name doesn't follow the MCP tool naming rule.

Track tool calls with runtime hooks

When the MCP Server handler invokes an API route for a tool, the global runtime hooks run for both the client request and the internal route invocation. Each invocation has its own request and context:

Path and query arguments become URL parameters, and declared header arguments become request headers. A GET tool invocation has no request body.

Use context.parentContext to distinguish client requests from internal invocations. It identifies any internal route invocation, including calls made with context.invokeRoute in your own code.

To log only the API route invocations for MCP tools, add this global request hook in modules/zuplo.runtime.ts:

Code
import { RuntimeExtensions, ZuploMcpSdk } from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addRequestHook((request, context) => {
    const toolCall = new ZuploMcpSdk(context).getRawCallToolRequest();

    if (context.parentContext && toolCall) {
      context.log.info({
        toolName: toolCall.params.name,
        method: request.method,
        path: new URL(request.url).pathname,
        requestId: context.requestId,
        contextId: context.contextId,
      });
    }

    return request;
  });
}

This logs a tool's API route invocation without also counting the outer /mcp request. To count only client requests instead, filter for context.parentContext === undefined. The SDK helper reads the current context and its immediate parent; see MCP metadata in runtime hooks for timing and nested-call details.

By default, the internal invocation shares the parent's requestId and has its own contextId. Use requestId to group related events and contextId to identify each execution. See Request/Response Hooks for hook behavior and response logging.

This extra hook execution applies when a tool invokes a Zuplo API route. Proxying to an upstream MCP server doesn't create an internal API route invocation for each tool call.

Testing MCP Tools

List Available Tools

Use the MCP tools/list method to see available tools:

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

Response:

Code
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "get_current_weather",
        "description": "Retrieve current weather conditions for a specified location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        }
      }
    ]
  }
}

Call a Tool

Use the MCP tools/call method to execute a tool:

Code
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": "get_current_weather",
      "arguments": {
        "location": "San Francisco"
      }
    }
  }'

Response:

Code
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"location\":\"San Francisco\",\"temperature\":72,\"condition\":\"Sunny\"}"
      }
    ]
  }
}

Best Practices

Meaningful Names and Descriptions

Always set meaningful operationIds (like get_users, create_new_deployment, or update_shopping_cart) and descriptions as these help LLMs understand exactly what each tool does.

When you need to provide more meaningful descriptions or names that don't align well with the operationId, set the metadata in x-zuplo-route.mcp.

AI models rely heavily on tool descriptions to understand when and how to use a tool.

• Be Descriptive: Explain exactly what the tool does and what inputs it expects.
• Use Meaningful Names: Operation IDs like create_user or search_products are much better than op1 or endpoint.

Schema Design

Use descriptive and well-structured JSON schemas for your tools (in your OpenAPI requestBody and response). This is used by the server to validate MCP client inputs (that is, JSON generated by an LLM). Providing descriptive schemas ensures an MCP Client's LLM always has the appropriate context on exactly what arguments to provide to tools and can dramatically reduce invalid tool usage. This validation is done automatically.

Code
// Good! Uses descriptive names and specific types with limiters and formats.
{
  "type": "object",
  "required": ["userId"],
  "properties": {
    "userId": {
      "type": "string",
      "format": "uuid",
      "description": "Valid UUID for user ID"
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000,
      "description": "Amount in cents"
    }
  }
}

Code
// Bad! Confusing. What's "a"? What's "b"? An LLM won't understand this.
{
  "type": "object",
  "required": ["userId"],
  "properties": {
    "a": {
      "type": "string"
    },
    "b": {
      "type": "number"
    }
  }
}

Defining clear schemas in your OpenAPI document ensures your handler always receives valid data. The MCP server uses these schemas to validate arguments provided by the AI client before your handler is ever called. Input validation is an important part of MCP, so ensure you have strong validation in your OpenAPI JSON schemas!

Keep Tool Routes Private

A tool's route is also a REST endpoint that clients can reach directly. If AI clients should reach the operation only through the MCP server, add the Internal Only policy to the route with "status": 404. See Keep REST routes private.

Custom Tools

For complex workflows that don't map 1:1 to a single API route, or require advanced logic, consider using Custom MCP Tools.