Configuration

MCPlexer can be configured through four different planes. The desktop app and web UI are the recommended starting point.

Config Planes

Plane	Best For	What It Manages
Desktop App / Web UI	Recommended — visual management with validation	Everything: servers, workspaces, routes, auth, approvals
YAML File	Version-controlled, reproducible server definitions	Downstream servers only
CLI	Scripting and automation	Secrets, daemon, status checks
MCP Control Server	AI-driven introspection and management	Full gateway state via MCP tools

Desktop App & Web UI

The desktop app (Electron) and web UI are the easiest way to configure MCPlexer. They provide the same interface — the desktop app just wraps it with system tray and native notifications.

After running make install, open the dashboard at http://localhost:3333 or launch the desktop app.

From the UI you can:

Quick Setup — connect downstream servers with OAuth in a few clicks (GitHub, Linear, ClickUp, etc.)
Downstream Servers — add, edit, disable, and discover tools
Workspaces — create directory-scoped security contexts
Routes — define routing rules with priority, path globs, and tool patterns
Credentials — manage auth scopes and OAuth tokens
OAuth Providers — configure OAuth apps from built-in templates
Dry Run — test route resolution before going live
Install MCP — one-click install/uninstall of MCPlexer into client apps (Claude Desktop, Cursor, Codex, etc.)
Settings — configure slim tools, cache TTL, log level, Codex compatibility, and built-in tool description overrides
Dashboard — monitor active sessions, server health, and request metrics

UI validates as you go

The web UI checks for namespace conflicts, invalid globs, missing references, and other common mistakes before saving. It's harder to misconfigure than raw YAML.

YAML Configuration

The YAML config file defines downstream MCP servers. On startup, MCPlexer reads this file and syncs it to the database. Use this when you want config-as-code that lives in version control.

YAML manages servers only

Workspaces, route rules, auth scopes, and OAuth providers are managed through the UI or API — not YAML.

Example

yaml

downstream_servers:
  # stdio-based server — MCPlexer spawns and manages the process
  - id: github-mcp
    name: GitHub MCP Server
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    tool_namespace: github
    discovery: dynamic
    idle_timeout_sec: 300
    max_instances: 2
    restart_policy: on-failure
    cache:
      enabled: true
      ttl_seconds: 60
      max_entries: 100

  # HTTP-based server — MCPlexer connects to an existing endpoint
  - id: linear-mcp
    name: Linear MCP Server
    transport: http
    url: http://localhost:3001/mcp
    tool_namespace: linear
    discovery: dynamic

  # Minimal stdio server with defaults
  - id: filesystem-mcp
    name: Filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    tool_namespace: fs

Server Properties

Name	Type	Default	Description
`id`	string	—	Unique identifier. Used in route rules and process management.
`name`	string	—	Human-readable display name.
`transport`	stdio \| http	—	How MCPlexer communicates with this server.
`command`	string	—	Command to spawn the server process. Required for stdio.
`args`	string[]	—	Arguments passed to the command.
`url`	string	—	Endpoint URL. Required for HTTP transport.
`tool_namespace`	string	—	Prefix for all tools. Tools become namespace__toolname.
`discovery`	static \| dynamic	dynamic	static: tools cached at config time. dynamic: queried via tools/list at runtime.
`idle_timeout_sec`	int	300	Seconds of inactivity before the process is stopped. stdio only.
`max_instances`	int	1	Maximum concurrent process instances. stdio only.
`restart_policy`	string	on-failure	When to restart crashed processes. stdio only.
`cache.enabled`	bool	false	Enable response caching for this server.
`cache.ttl_seconds`	int	60	Cache entry time-to-live in seconds.
`cache.max_entries`	int	100	Maximum cached responses.

YAML Seeding Behavior

When MCPlexer starts, it syncs the YAML file to the database:

New servers in YAML are inserted into the database
Changed servers overwrite the database version
Removed servers that were seeded from YAML are pruned
Source tagging — each record tracks whether it came from YAML or the UI/API

Don't mix config sources

If a server was created via the UI, adding it to YAML will overwrite those settings. Keep each server in one config plane.

Environment Variables

Name	Type	Default	Description
`MCPLEXER_MODE`	string	stdio	Transport mode: stdio, http, or socket.
`MCPLEXER_HTTP_ADDR`	string	127.0.0.1:8080	Listen address for HTTP mode.
`MCPLEXER_DB_DRIVER`	string	sqlite	Database driver: sqlite or postgres.
`MCPLEXER_DB_DSN`	string	~/.mcplexer/mcplexer.db	Database connection string.
`MCPLEXER_CONFIG`	string	~/.mcplexer/mcplexer.yaml	Path to the YAML config file.
`MCPLEXER_AGE_KEY`	string	—	Path to the age encryption key file for secrets.
`MCPLEXER_SOCKET_PATH`	string	—	Unix socket path for daemon/socket mode.
`MCPLEXER_EXTERNAL_URL`	string	—	External URL for OAuth callback redirects.
`MCPLEXER_LOG_LEVEL`	string	info	Log level: debug, info, warn, error.
`MCPLEXER_SLIM_TOOLS`	bool	true	Minify tool schemas to reduce AI context window consumption.
`MCPLEXER_CODEX_DYNAMIC_TOOL_COMPAT`	bool	true	Auto-include dynamic-discovery tools in tools/list for Codex client sessions.
`MCPLEXER_CONTROL_READONLY`	bool	true	Read-only mode for the control server.

MCP Control Server

The control server exposes MCPlexer's state as an MCP server — allowing AI clients to inspect and manage the gateway programmatically.

terminal

mcplexer control-server

Set MCPLEXER_CONTROL_READONLY=true to restrict to read-only operations. See Control Server for the full tool reference.

Concepts CLI Reference