MCP Server

MCP Server Tools

Copy page

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: Set to "tool" (optional, as this is the default)
• name (optional) - The identifier for the MCP tool. Defaults to the operation's operationId.
• description (optional) - Description of what the tool does. Falls back to the operation's description or summary.
• enabled (optional) - Whether this tool is enabled. Defaults to true.

The route handler for your tool is any standard Zuplo request handler like the URL Fowarder 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"
                }
              ]
            }
          }
        }
      }
    }
  }
}

The operations array supports:

• file - Path to the OpenAPI specification file containing tool routes
• id - The operation ID to include as an MCP tool

Route Handler Implementation

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"]
        }
      }
    ]
  }
}

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\"}"
      }
    ]
  }
}

Tool names and descriptions

MCP tools are configured as follows:

• Tool names: Uses the route's operationId if available, otherwise falls back to a generated METHOD_ROUTE format (for example, GET_todos)
• Tool descriptions: Derived from (in order of priority):
  1. The route's description field
  2. The route's summary field
  3. A generated description if neither is available

Best Practice: 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.

Best Practices

Tool Descriptions

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.

Input Validation

Define clear schemas in your OpenAPI document. The MCP server uses these schemas to validate arguments provided by the AI client before your handler is ever called. This ensures your handler receives valid data.

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.