How to Migrate Existing MCP Servers to MetaMCP Endpoints: A Step-by-Step Guide

Migrating existing MCP servers to MetaMCP endpoints involves a three-stage process: preparing the MetaMCP backend with database migrations, exporting current server configurations to JSON format, and importing them via the MetaMCP dashboard or API to generate centralized, namespaced endpoints.

MetaMCP (maintained in the metatool-ai/metamcp repository) transforms standalone Model Context Protocol servers into managed, routable endpoints through a unified control plane. If you currently operate multiple disparate MCP servers, migrating them to MetaMCP endpoints consolidates authentication, enables bulk configuration management, and provides centralized observability. This guide references the actual source code implementation to walk you through provisioning, exporting, and importing your server definitions.

Stage 1: Prepare the MetaMCP Backend

Before importing existing servers, you must provision the MetaMCP infrastructure and initialize the PostgreSQL schema that stores server metadata, namespaces, and endpoint configurations.

Clone and Install Dependencies

Pull the monorepo and install all workspace dependencies using pnpm.

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
pnpm install

Configure Environment Variables

Copy the example environment file to supply database connection strings, JWT secrets, and other runtime configuration. According to the repository's contributing guide, you should copy example.env to .env.local for local development or edit .env for Docker deployments.

cp example.env .env.local

Execute Database Migrations

Run the migration script to create the PostgreSQL schema defined in apps/backend/src/db/schema.ts. This schema stores MCP server metadata, namespace mappings, and tool registrations.

pnpm db:migrate:dev

For Docker deployments, the docker-entrypoint.sh script automatically executes these migrations when the container starts, ensuring the database is ready before the application accepts connections. As documented in docs/en/development/contributing.mdx (lines 64-70), this step is required for first-time setups.

Verify the installation by starting the development server (pnpm dev) and accessing the dashboard at http://localhost:3000.

Stage 2: Export Current MCP Server Definitions

MetaMCP provides a bulk export feature that serializes your existing server configurations into a standardized JSON format compatible with the import system.

Accessing the Export Feature

Navigate to the MCP Servers section in the MetaMCP dashboard and click "Export JSON". You can download the file or copy the payload to your clipboard. This functionality is documented in docs/en/concepts/mcp-servers.mdx (lines 218-226).

Understanding the Export Format

The exported JSON follows a strict schema that supports STDIO, Server-Sent Events (SSE), and Streamable HTTP transport types. As defined in docs/en/concepts/mcp-servers.mdx (lines 218-256), the structure nests server configurations under the mcpServers key:

{
  "mcpServers": {
    "HackerNews": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-hn"],
      "description": "Access HackerNews stories and comments"
    },
    "TimeServer": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time"],
      "env": { "TZ": "America/New_York" },
      "description": "Time and timezone utilities"
    },
    "RemoteAPI": {
      "type": "streamable_http",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token",
      "headers": { "X-API-Version": "v2" },
      "description": "Remote MCP server via HTTP"
    }
  }
}

If your current servers are not yet managed by MetaMCP, manually construct a JSON file following this schema to prepare for import.

Stage 3: Import into MetaMCP and Update Clients

Once you have the JSON definition file, import it into MetaMCP to create managed endpoints and reconfigure your client applications to use the new centralized URLs.

Bulk Import via Dashboard

The MetaMCP dashboard provides a bulk import interface accessible at MCP Servers → Import JSON. Paste your exported JSON or upload the file, then click Import. The system reports success and failure counts, updating existing server definitions when names collide and creating new entries for unique names. This process is detailed in docs/en/concepts/mcp-servers.mdx (lines 260-300).

Organize with Namespaces

After import, assign servers to logical namespaces (e.g., production, analytics, or utilities). Each namespace generates a unique MetaMCP endpoint URL (SSE or HTTP) that proxies requests to the underlying servers. This namespace-based routing is defined in the schema at apps/backend/src/db/schema.ts.

Reconfigure Client Applications

Update your client code to replace direct server invocations with MetaMCP endpoint URLs. The following TypeScript example demonstrates migrating from a direct STDIO command to a managed HTTP endpoint:

import { McpClient } from "@modelcontextprotocol/sdk/client";

// Legacy direct invocation
const oldClient = new McpClient({ 
  command: "uvx", 
  args: ["mcp-hn"] 
});

// New MetaMCP managed endpoint
const newClient = new McpClient({ 
  url: "https://meta.mcp.example.com/namespace/news" 
});

Programmatic Migration Using the API

For automated fleet migrations, MetaMCP exposes the POST /api/mcp-servers/import endpoint. This accepts the same JSON payload used by the dashboard import feature.

curl -X POST https://meta.mcp.example.com/api/mcp-servers/import \
  -H "Authorization: Bearer $META_MCP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d @exported-servers.json

Security requirement: The admin token must possess the admin scope. Store this token in a secret manager—never commit it to source control.

Summary

• Provision the backend by running pnpm db:migrate:dev (or using Docker auto-migration via docker-entrypoint.sh) to initialize the PostgreSQL schema defined in apps/backend/src/db/schema.ts.
• Export existing configurations using the dashboard's Export JSON feature, which generates a standardized mcpServers JSON object documented in docs/en/concepts/mcp-servers.mdx.
• Import via UI or API using the POST /api/mcp-servers/import endpoint or the dashboard import interface; existing servers update automatically while new ones are created.
• Reconfigure clients to use MetaMCP namespace endpoints instead of direct command/URL invocations, enabling centralized management and authentication.

Frequently Asked Questions

Does MetaMCP support migrating servers using different transport protocols?

Yes. The JSON import format documented in docs/en/concepts/mcp-servers.mdx supports stdio, sse, and streamable_http transport types within the same payload. You can migrate a mixed fleet of local command-line tools and remote HTTP services simultaneously.

What happens if a server with the same name already exists during import?

MetaMCP performs an upsert operation. When the import process encounters a server name that already exists in the database (defined in apps/backend/src/db/schema.ts), it updates the existing configuration with the new JSON values rather than creating duplicates.

Can I automate migration without using the web dashboard?

Yes. Use the POST /api/mcp-servers/import endpoint with an admin-scoped bearer token. This API accepts the identical JSON format used by the dashboard bulk import feature, enabling CI/CD pipelines to migrate servers programmatically.

Is database downtime required during the migration process?

No. The migration process involves exporting definitions from existing systems and importing them into the MetaMCP PostgreSQL database via standard insert/update operations. Existing MCP servers continue operating normally until you reconfigure clients to point to the new MetaMCP endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}