A MCP Server is a configuration that tells MetaMCP how to start and manage a Model Context Protocol server. These servers provide tools, resources, and prompts that can be aggregated and exposed through MetaMCP endpoints.

​
What is a MCP Server?

MCP Servers are the building blocks of MetaMCP. Each server configuration defines:
  • How to start the server (command, arguments, environment)
  • What type of server it is (STDIO, SSE, Streamable HTTP)
  • Authentication requirements (if any)
  • Resource dependencies (Python packages, Node modules, etc.)

Example Configuration

{
  "name": "HackerNews",
  "type": "STDIO", 
  "command": "uvx",
  "args": ["mcp-hn"],
  "description": "Access HackerNews stories and comments"
}

​
Server Types

MetaMCP supports three types of MCP servers:

​
Configuration Options

​
Basic Configuration

{
  "name": "unique-server-name",
  "type": "STDIO|SSE|STREAMABLE_HTTP",
  "command": "command-to-run", // STDIO only
  "args": ["arg1", "arg2"],     // STDIO only
  "url": "https://...",         // SSE/STREAMABLE_HTTP only
}

​
Environment Variables

Pass environment variables to STDIO servers: 
{
  "name": "TimeServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-server-time", "--local-timezone=America/New_York"],
  "env": {
    "TZ": "America/New_York"
  }
}

​
Environment Variable Interpolation

Use ${ENV_VAR} syntax to reference environment variables at runtime: 
{
  "name": "ExampleServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-example"],
  "env": {
    "API_KEY": "${API_KEY}",
    "DEBUG": "true"
  }
}
Benefits:
  • Secure: API keys and secrets aren’t hardcoded in configs
  • Flexible: Values resolved from container environment
  • Backward compatible: Raw values still work as before
How it works:
  • ${VAR_NAME} gets replaced with process.env.VAR_NAME at runtime
  • Missing variables log a warning but don’t crash the server
  • Secrets are automatically redacted in logs

​
Authentication

For servers requiring authentication: 
{
  "env": {
    "API_KEY": "your-secret-key"
  }
}

​
Managing MCP Servers

​
Adding Servers

  1. Navigate to MCP Servers in the MetaMCP dashboard
  2. Click “Add Server”
  3. Configure the server details
  4. Test the configuration
  5. Save to make it available for namespaces

​
Bulk Import/Export

MetaMCP supports bulk import and export of MCP server configurations for easy migration and backup.

​
Exporting Servers

Export all your configured MCP servers to a JSON file:
  1. Navigate to MCP Servers in the dashboard
  2. Click “Export JSON” button
  3. Choose to either download the file or copy to clipboard

Export Format

{
  "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",
      "description": "Remote MCP server via HTTP"
    }
  }
}

​
Importing Servers

Import multiple MCP servers from a JSON configuration:
  1. Navigate to MCP Servers in the dashboard
  2. Click “Import JSON” button
  3. Paste or type your JSON configuration
  4. Click “Import” to add the servers
{
  "mcpServers": {
    "ServerName": {
      "type": "stdio",
      "command": "uvx",
      "args": ["package-name"],
      "env": {
        "API_KEY": "your-key"
      },
      "description": "Optional description"
    }
  }
}
Type Values (Case-Insensitive):
  • "stdio", "STDIO", "std" → STDIO
  • "sse", "SSE" → SSE
  • "streamable_http", "STREAMABLE_HTTP", "streamablehttp", "http" → STREAMABLE_HTTP
Import Behavior:
  • Servers with existing names will be updated with new configuration
  • New servers will be created
  • Invalid configurations will be skipped with error messages
  • The import process shows success/failure counts
Use bulk import/export for:
  • Environment migration (dev → staging → production)
  • Team collaboration (sharing server configurations)
  • Backup and restore (configuration backups)
  • Quick setup (deploying multiple servers at once)

​
Idle Session Management

MetaMCP pre-allocates idle sessions for better performance:

Cold Start Optimization

  • Default: 1 idle session per server
  • Configurable: Adjust based on usage patterns
  • Auto-scaling: Sessions created on demand
  • Cleanup: Idle sessions recycled after timeout

​
Custom Dockerfile for Dependencies

If your MCP servers require additional dependencies beyond uvx or npx, you can customize the MetaMCP Dockerfile: 
FROM metamcp:latest

# Install Python dependencies
RUN pip install requests beautifulsoup4

# Install system packages
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js packages globally
RUN npm install -g some-mcp-package
Custom dependencies increase the Docker image size and startup time. Consider using lightweight alternatives when possible.

​
Troubleshooting

​
Next Steps

Create Namespaces

Group your MCP servers into organized namespaces

Set Up Endpoints

Create public endpoints to access your servers

Add Middleware

Transform and filter MCP requests and responses

Integration Guide

Connect your configured servers to MCP clients