MCP Servers

MCP (Model Context Protocol) lets you connect external tool servers to muxd. An MCP server is a separate process that exposes tools over a standard protocol — muxd discovers the tools automatically and makes them available to the agent. Servers can use stdio (local process) or HTTP transport.

Configuration

MCP servers are configured in JSON files at two scopes:

Scope	File	Description
Project	`.mcp.json` in project root	Shared with your team via version control
User	`~/.config/muxd/mcp.json`	Personal servers available in all projects

Both files use the same format:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {}
    }
  }
}

When the same server name appears in both files, the project config wins.

Stdio Transport

Stdio servers run as a local child process. muxd communicates with them over stdin/stdout.

Field	Type	Required	Description
`type`	string	no	`"stdio"` (default if omitted)
`command`	string	yes	Executable to run
`args`	string[]	no	Command-line arguments
`env`	object	no	Environment variables to set

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {
        "DEBUG": "1"
      }
    }
  }
}

HTTP Transport

HTTP servers run independently and expose an HTTP endpoint. Use this for remote or shared servers.

Field	Type	Required	Description
`type`	string	yes	`"http"`
`url`	string	yes	Server endpoint URL

{
  "mcpServers": {
    "remote-tools": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Environment Variable Expansion

Config values support ${VAR} expansion with optional defaults:

Syntax	Behavior
`${VAR}`	Replaced with the value of `VAR`, or empty string if unset
`${VAR:-default}`	Replaced with `VAR` if set, otherwise `default`

This works in all string fields — command, args, url, and env values:

{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "${MCP_API_URL:-http://localhost:3000}"
    },
    "db": {
      "command": "python",
      "args": ["${DB_SERVER_SCRIPT:-./mcp_db.py}"],
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

Tool Namespacing

MCP tools are namespaced to avoid collisions with built-in tools and between servers. The format is:

mcp__<server-name>__<tool-name>

Server names are normalized to lowercase with non-alphanumeric characters (except hyphens) replaced by hyphens. For example, a server named filesystem exposing a read_file tool becomes mcp__filesystem__read_file.

The agent sees these tools alongside built-in tools and can call them in the same way.

Verifying

Use /config tools or /tools to see all available tools including MCP servers and their connection status:

/config tools
/tools list

Server statuses: connected, connecting, disconnected, or error.

Examples

Filesystem server

Give the agent access to a specific directory:

{
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

Context7 documentation server

Look up library documentation from within the agent:

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

Fetch server

Let the agent fetch URLs and extract content:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}