> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metamcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Learn how to configure and manage MCP server instances in MetaMCP

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.)

<Card title="Example Configuration" icon="code">
  ```json theme={null}
  {
    "name": "HackerNews",
    "type": "STDIO", 
    "command": "uvx",
    "args": ["mcp-hn"],
    "description": "Access HackerNews stories and comments"
  }
  ```
</Card>

## Server Types

MetaMCP supports three types of MCP servers:

<AccordionGroup>
  <Accordion icon="terminal" title="STDIO Servers">
    **Most common type** - Communicates via standard input/output streams

    ```json theme={null}
    {
      "type": "STDIO",
      "command": "uvx", 
      "args": ["mcp-server-package"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
    ```

    **Use cases:**

    * Python packages installed via `uvx`
    * Node.js packages via `npx`
    * Custom executable scripts
  </Accordion>

  <Accordion icon="globe" title="SSE Servers">
    **Server-Sent Events** - Communicates via SSE (Server-Sent Events)

    ```json theme={null}
    {
      "type": "SSE",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-bearer-token",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
    ```

    <Info>You can leave bearerToken as blank if the server uses OAuth.</Info>
  </Accordion>

  <Accordion icon="globe" title="Streamable HTTP Servers">
    **HTTP-based streaming** - Streamable HTTP is now the standard for remote MCP

    ```json theme={null}
    {
      "type": "STREAMABLE_HTTP",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
    ```

    <Info>You can leave bearerToken as blank if the server uses OAuth.</Info>
  </Accordion>
</AccordionGroup>

## Configuration Options

### Basic Configuration

<CodeGroup>
  ```json Required Fields theme={null}
  {
    "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
  }
  ```

  ```json Optional Fields theme={null}
  {
    "description": "Human-readable description",
    "env": {
      "KEY": "value"
    },
    "bearerToken": "auth-token",  // SSE/STREAMABLE_HTTP only
    "headers": {                  // SSE/STREAMABLE_HTTP only
      "X-Custom-Header": "value"
    }
  }
  ```
</CodeGroup>

### Environment Variables

Pass environment variables to STDIO servers:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

<CodeGroup>
  ```json STDIO with API Keys theme={null}
  {
    "env": {
      "API_KEY": "your-secret-key"
    }
  }
  ```

  ```json Remote with Bearer Token theme={null}
  {
    "bearerToken": "your-bearer-token"
  }
  ```
</CodeGroup>

### Custom Headers

Add custom HTTP headers to **SSE and Streamable HTTP servers**:

```json theme={null}
{
  "type": "SSE",
  "url": "https://api.example.com/sse",
  "headers": {
    "X-API-Key": "your-api-key",
    "X-API-Version": "v2",
    "Organization-ID": "org-123"
  }
}
```

<Tip>
  Useful when your server requires:

  * Multiple authentication headers (API keys + bearer tokens)
  * Gateway or proxy authentication
  * Organization-specific headers
</Tip>

## 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

<Card title="Export Format" icon="code">
  ```json theme={null}
  {
    "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"
      }
    }
  }
  ```
</Card>

#### 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

<CodeGroup>
  ```json STDIO Server Format theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "stdio",
        "command": "uvx",
        "args": ["package-name"],
        "env": {
          "API_KEY": "your-key"
        },
        "description": "Optional description"
      }
    }
  }
  ```

  ```json SSE Server Format theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "sse",
        "url": "https://api.example.com/sse",
        "bearerToken": "your-token",
        "headers": {
          "X-Custom-Header": "value"
        },
        "description": "Optional description"
      }
    }
  }
  ```

  ```json Streamable HTTP Format theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "streamable_http",
        "url": "https://api.example.com/mcp",
        "bearerToken": "your-token",
        "headers": {
          "X-Custom-Header": "value"
        },
        "description": "Optional description"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  **Type Values (Case-Insensitive):**

  * `"stdio"`, `"STDIO"`, `"std"` → STDIO
  * `"sse"`, `"SSE"` → SSE
  * `"streamable_http"`, `"STREAMABLE_HTTP"`, `"streamablehttp"`, `"http"` → STREAMABLE\_HTTP
</Note>

<Note>
  **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
</Note>

<Tip>
  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)
</Tip>

### Idle Session Management

MetaMCP pre-allocates idle sessions for better performance:

<Card title="Cold Start Optimization" icon="zap">
  * **Default**: 1 idle session per server
  * **Configurable**: Adjust based on usage patterns
  * **Auto-scaling**: Sessions created on demand
  * **Cleanup**: Idle sessions recycled after timeout
</Card>

## Custom Dockerfile for Dependencies

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

```dockerfile theme={null}
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
```

<Warning>
  Custom dependencies increase the Docker image size and startup time. Consider using lightweight alternatives when possible.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="triangle-alert" title="Server Won't Start">
    **Common causes:**

    * Missing dependencies (install via custom Dockerfile)
    * Incorrect command or arguments
    * Environment variables not set
    * Network connectivity issues (for SSE/Streamable HTTP)

    **Debug steps:**

    1. Check server logs in MetaMCP dashboard
    2. Test command manually in terminal
    3. Verify environment variables
    4. Check network connectivity
  </Accordion>

  <Accordion icon="clock" title="Slow Performance">
    **Optimization strategies:**

    * Increase idle session count for frequently used servers
    * Use local servers instead of remote when possible
    * Pre-install dependencies in custom Docker image
    * Configure appropriate timeout values
  </Accordion>

  <Accordion icon="shield" title="Authentication Issues">
    **Common problems:**

    * Expired API keys or bearer tokens
    * Incorrect environment variable names
    * Missing required headers
    * Rate limiting from external APIs

    **Solutions:**

    1. Refresh API keys/tokens
    2. Check server documentation for required auth
    3. Implement proper error handling
    4. Add retry logic with backoff
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Namespaces" icon="package" href="/en/concepts/namespaces">
    Group your MCP servers into organized namespaces
  </Card>

  <Card title="Set Up Endpoints" icon="link" href="/en/concepts/endpoints">
    Create public endpoints to access your servers
  </Card>

  <Card title="Add Middleware" icon="filter" href="/en/concepts/middleware">
    Transform and filter MCP requests and responses
  </Card>

  <Card title="Integration Guide" icon="plug" href="/en/integrations/cursor">
    Connect your configured servers to MCP clients
  </Card>
</CardGroup>