Using MCP Servers with amux Sessions

MCP servers give agents access to databases, APIs, browsers, and internal tools. Here's how to configure them in amux.

What MCP Servers Do

Model Context Protocol (MCP) is an open standard that lets Claude Code connect to external tool servers. Each MCP server exposes a set of tools that the agent can use: query a database, search the web, post to Slack, create GitHub issues, control a browser. With MCP, agents become systems — not just code writers.

The amux mcp.json Config

amux uses a centralized mcp.json in the project root for MCP server configuration. This file is shared by all sessions:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Useful MCP Servers for Coding Agents

MCP Server	What it enables	Install
server-filesystem	Controlled file access with path restrictions	@modelcontextprotocol/server-filesystem
server-github	Create PRs, issues, search code	@modelcontextprotocol/server-github
server-postgres	Query live database schema and data	@modelcontextprotocol/server-postgres
server-puppeteer	Browser automation and screenshots	@modelcontextprotocol/server-puppeteer
server-brave-search	Web search for docs and examples	@modelcontextprotocol/server-brave-search
server-slack	Post messages, read channels	@modelcontextprotocol/server-slack

Security Considerations

Never put production database URLs in mcp.json if it's committed. Use environment variable references and keep secrets in ~/.amux/server.env.
Use path restrictions for filesystem MCP. Specify exactly which directories agents are allowed to access.
Scope GitHub tokens. Give agents tokens with only the permissions they need (read repo, write PRs — not admin, not billing).

Testing Your MCP Setup

# Start a session and verify MCP tools are available
amux start myagent
# Then in the dashboard, peek at the session and run:
# "List the MCP tools available to you"

Get started with amux

Run dozens of Claude Code agents in parallel. Python 3 + tmux. Open source.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822

View on GitHub