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

> Migrate existing MCP servers to MetaMCP endpoints with our step-by-step guide. Learn to prepare the backend, export configurations, and import them for centralized management.

- Repository: [metatool-ai/metamcp](https://github.com/metatool-ai/metamcp)
- Tags: migration-guide
- Published: 2026-03-07

---

**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`.

```bash
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.

```bash
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`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/db/schema.ts). This schema stores MCP server metadata, namespace mappings, and tool registrations.

```bash
pnpm db:migrate:dev

```

For Docker deployments, the [`docker-entrypoint.sh`](https://github.com/metatool-ai/metamcp/blob/main/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:

```json
{
  "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`](https://github.com/metatool-ai/metamcp/blob/main/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:

```typescript
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.

```bash
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`](https://github.com/metatool-ai/metamcp/blob/main/docker-entrypoint.sh)) to initialize the PostgreSQL schema defined in [`apps/backend/src/db/schema.ts`](https://github.com/metatool-ai/metamcp/blob/main/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`](https://github.com/metatool-ai/metamcp/blob/main/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.