Configuration

Config file format

MetaMCP reads .mcp.json by default. The format is the same as Claude Desktop and Claude Code config files.

{
  "mcpServers": {
    "<server-name>": {
      "command": "<executable>",
      "args": ["<arg1>", "<arg2>"],
      "env": {
        "<VAR>": "<value>"
      }
    }
  }
}

Each key under mcpServers is a server name. MetaMCP uses this name to identify the server in mcp_discover, mcp_call, and mcp_execute.

To use a different config file path, pass it with the --config flag:

metamcp --config path/to/my-config.json

Server entry fields

Each server entry supports the following fields:

* Each entry must have either command (for local stdio servers) or url (for remote HTTP/SSE servers).

npx packages

Most MCP servers are distributed as npm packages. Use npx as the command to run them without a global install:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The -y flag auto-confirms the npx install prompt. Without it, npx may hang waiting for user confirmation.

You can pin a specific version by replacing @latest with a version number (e.g., @playwright/mcp@0.0.10).

Local binaries

For servers installed locally or built from source, use an absolute path:

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/my-mcp-server",
      "args": ["--port", "3000"]
    }
  }
}

Environment variables

Pass server-specific environment variables using the env field:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Environment variables in the env field are passed only to that child server's process. They do not leak to other servers or to MetaMCP itself.

Remote servers

MetaMCP can connect to remote MCP servers over HTTP or SSE. Use the url field instead of command:

Streamable HTTP (default for remote):

{
  "mcpServers": {
    "cloud-tools": {
      "url": "https://mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

SSE transport:

{
  "mcpServers": {
    "sse-server": {
      "url": "https://mcp.example.com/sse",
      "transportType": "sse"
    }
  }
}

OAuth authorization:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://mcp.example.com/api",
      "oauth": true
    }
  }
}

When oauth is true, MetaMCP opens your browser for authorization on first connect. Tokens are persisted at ~/.metamcp/oauth/<server-name>/ and refreshed automatically on subsequent runs.

Config discovery

The metamcp init command auto-detects installed MCP clients and configures them to use MetaMCP:

metamcp init

This detects Claude Desktop, Claude Code, and other supported clients. It writes the appropriate config entries so you do not need to edit config files manually.

For the full list of init options, see CLI Reference.

CLI overrides

CLI flags override the built-in defaults for connection pool and circuit breaker behavior. Pass them when starting MetaMCP:

metamcp --config .mcp.json --max-connections 10 --idle-timeout 60000

For the complete CLI reference, see CLI Reference.

Next steps

• Adding Servers for patterns and tips on configuring different types of child servers.
• Config Schema Reference for the full JSON schema of .mcp.json.