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.

Server lifecycle

Each server can declare how MetaMCP manages its connection lifetime. Without a lifecycle declaration, servers follow the global idle timeout (default: 5 minutes).

Keep-alive (persistent connection):

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db"],
      "lifecycle": "keep-alive"
    }
  }
}

Keep-alive servers are exempt from the global idle timeout sweep. They remain connected until MetaMCP shuts down. This is ideal for servers with expensive initialization or persistent state.

Keep-alive with per-server idle timeout:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db"],
      "lifecycle": { "mode": "keep-alive", "idleTimeoutMs": 600000 }
    }
  }
}

The server uses its own idle timeout (10 minutes in this example) instead of the global default. It is still exempt from the global sweep and only evicted after its own timeout expires.

Ephemeral (connect on demand):

{
  "mcpServers": {
    "converter": {
      "command": "/usr/local/bin/converter",
      "lifecycle": "ephemeral"
    }
  }
}

Ephemeral servers are torn down as soon as they go idle. They are spawned fresh on each use. This suits stateless, fast-starting utilities where keeping a process alive wastes resources.

Importing from editors

MetaMCP can auto-discover MCP server configurations from your installed editors and development tools. Pass the --import flag to merge external configs at startup:

metamcp --config .mcp.json --import

MetaMCP scans the following clients for configured MCP servers:

Discovered servers are merged with your local .mcp.json configuration. Local config takes precedence: if a server name appears in both your config file and an editor, the local definition wins. Among editors, first-seen wins.

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.