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:
operationsarray with simple{ file, id }references - ❌ Deprecated:
files,tools,prompts,resourcesarrays
Operation Extensions:
- ✅ New: Single
x-zuplo-route.mcpextension withtypefield - ❌ Deprecated: Separate
x-zuplo-mcp-tool,x-zuplo-mcp-prompt,x-zuplo-mcp-resource,x-zuplo-mcp-graphqlextensions
Migration Steps
Step 1: Update Handler Options
Old Syntax:
Code
New Syntax:
Code
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:
Code
New Syntax:
Code
Prompts
Old Syntax:
Code
New Syntax:
Code
Resources
Old Syntax:
Code
New Syntax:
Code
GraphQL
Old Syntax:
Code
New Syntax:
Code
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:
Code
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,resourcesarrays with singleoperationsarray - Change
pathtofileandoperationIdsto individual{ file, id }objects - Move
x-zuplo-mcp-toolintox-zuplo-route.mcpwithtype: "tool" - Move
x-zuplo-mcp-promptintox-zuplo-route.mcpwithtype: "prompt" - Move
x-zuplo-mcp-resourceintox-zuplo-route.mcpwithtype: "resource" - Move
x-zuplo-mcp-graphqlintox-zuplo-route.mcpwithtype: "graphql" - Update GraphQL field names:
introspectionToolName→introspectionTool.name,executeToolName→executeTool.name, or on compatibility date2026-11-06and later, configureschemaTool,queryTool, andmutationToolinstead - 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.