MCP Server

MCP Server Configuration Migration Guide

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

This guide explains how to migrate from the deprecated MCP server configuration syntax to the new consolidated format introduced in November 2025.

What Changed

The new configuration consolidates and simplifies MCP server setup:

Handler Options:

  • ✅ New: operations array with simple { file, id } references
  • ❌ Deprecated: files, tools, prompts, resources arrays

Operation Extensions:

  • ✅ New: Single x-zuplo-route.mcp extension with type field
  • ❌ Deprecated: Separate x-zuplo-mcp-tool, x-zuplo-mcp-prompt, x-zuplo-mcp-resource, x-zuplo-mcp-graphql extensions

Migration Steps

Step 1: Update Handler Options

Old Syntax:

JSONCode
{ "handler": { "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "name": "my MCP server", "version": "0.0.0", "files": [ { "path": "./config/routes.oas.json", "operationIds": ["list-users", "create-user"] } ], "prompts": [ { "path": "./config/routes.oas.json", "operationIds": ["greeting"] } ], "resources": [ { "path": "./config/routes.oas.json", "operationIds": ["html"] } ] } } }

New Syntax:

JSONCode
{ "handler": { "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "name": "my MCP server", "version": "0.0.0", "operations": [ { "file": "./config/routes.oas.json", "id": "list-users" }, { "file": "./config/routes.oas.json", "id": "create-user" }, { "file": "./config/routes.oas.json", "id": "greeting" }, { "file": "./config/routes.oas.json", "id": "html" } ] } } }

All operations (tools, prompts, resources) now go into a single operations array. The type is determined by the x-zuplo-route.mcp.type field on each operation.

Step 2: Update Operation Extensions

Tools

Old Syntax:

JSONCode
{ "paths": { "/users": { "get": { "operationId": "list-users", "summary": "List all users", "x-zuplo-route": { "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)" } }, "x-zuplo-mcp-tool": { "name": "get_all_users", "description": "Use this tool to retrieve a list of all registered users" } } } } }

New Syntax:

JSONCode
{ "paths": { "/users": { "get": { "operationId": "list-users", "summary": "List all users", "x-zuplo-route": { "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)" }, "mcp": { "type": "tool", "name": "get_all_users", "description": "Use this tool to retrieve a list of all registered users" } } } } } }

Prompts

Old Syntax:

JSONCode
{ "paths": { "/greeting": { "post": { "operationId": "greeting", "summary": "Generate a greeting message", "x-zuplo-mcp-prompt": { "name": "greeting_generator", "description": "Generate a personalized greeting message" } } } } }

New Syntax:

JSONCode
{ "paths": { "/greeting": { "post": { "operationId": "greeting", "summary": "Generate a greeting message", "x-zuplo-route": { "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)" }, "mcp": { "type": "prompt", "name": "greeting_generator", "description": "Generate a personalized greeting message" } } } } } }

Resources

Old Syntax:

JSONCode
{ "paths": { "/html": { "get": { "operationId": "html", "summary": "HTML document", "x-zuplo-mcp-resource": { "name": "html_doc", "description": "An HTML document resource", "uri": "ui://html", "mimeType": "text/html" } } } } }

New Syntax:

JSONCode
{ "paths": { "/html": { "get": { "operationId": "html", "summary": "HTML document", "x-zuplo-route": { "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)" }, "mcp": { "type": "resource", "name": "html_doc", "description": "An HTML document resource", "uri": "ui://html", "mimeType": "text/html" } } } } } }

GraphQL

Old Syntax:

JSONCode
{ "paths": { "/graphql": { "post": { "operationId": "graphql-api", "summary": "GraphQL API endpoint", "x-zuplo-mcp-graphql": { "enabled": true, "introspectionToolName": "graphql_introspect", "executeToolName": "graphql_execute" } } } } }

New Syntax:

JSONCode
{ "paths": { "/graphql": { "post": { "operationId": "graphql-api", "summary": "GraphQL API endpoint", "x-zuplo-route": { "handler": { "export": "urlForwardHandler", "module": "$import(@zuplo/runtime)" }, "mcp": { "type": "graphql", "enabled": true, "introspectionTool": { "name": "graphql_introspect", "description": "Introspect the GraphQL schema" }, "executeTool": { "name": "graphql_execute", "description": "Execute a GraphQL query" } } } } } } }

From compatibility date 2026-11-06, a GraphQL route in x-zuplo-route.mcp gets schema, query, and mutation tools instead, and introspectionTool and executeTool fail the build. On that date, leave them out and configure the tools with schemaTool, queryTool, and mutationTool. See Schema, query, and mutation tools.

The deprecated x-zuplo-mcp-graphql extension keeps its introspection and execute tools whatever the compatibility date. Moving the same configuration to x-zuplo-route.mcp on compatibility date 2026-11-06 or later therefore changes the tools your MCP clients see: {operationId}_schema, {operationId}_query, and {operationId}_mutation replace the introspection and execute tools. Update any client, prompt, or allowlist that refers to the old tool names when you migrate.

New Features

Enabled Flag

The new syntax supports an enabled flag on all types to conditionally include operations:

JSONCode
{ "x-zuplo-route": { "mcp": { "type": "tool", "name": "disabled_tool", "enabled": false } } }

When enabled: false, the operation is skipped during registration without needing to remove it from the configuration.

Improved Validation

The new format includes OpenAPI schema validation via oneOf constraints, providing better IDE support and error messages.

Quick Migration Checklist

  • Replace files, tools, prompts, resources arrays with single operations array
  • Change path to file and operationIds to individual { file, id } objects
  • Move x-zuplo-mcp-tool into x-zuplo-route.mcp with type: "tool"
  • Move x-zuplo-mcp-prompt into x-zuplo-route.mcp with type: "prompt"
  • Move x-zuplo-mcp-resource into x-zuplo-route.mcp with type: "resource"
  • Move x-zuplo-mcp-graphql into x-zuplo-route.mcp with type: "graphql"
  • Update GraphQL field names: introspectionToolName → introspectionTool.name, executeToolName → executeTool.name, or on compatibility date 2026-11-06 and later, configure schemaTool, queryTool, and mutationTool instead
  • Test your MCP server to ensure all operations are registered correctly

Backward Compatibility

The old syntax is currently marked as deprecated but still functional. However, it will be removed in a future release, so migration is recommended as soon as possible.

Last modified on