Copy page

MCP Server Configuration Migration Guide

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:

Code
{
  "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:

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

Step 2: Update Operation Extensions

Tools

Old Syntax:

Code
{
  "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:

Code
{
  "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:

Code
{
  "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:

Code
{
  "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:

Code
{
  "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:

Code
{
  "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:

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

New Syntax:

Code
{
  "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"
            }
          }
        }
      }
    }
  }
}

New Features

Enabled Flag

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

Code
{
  "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
• 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.