MCP Guide
MCP (Model Context Protocol) is how Claude Code agents interact with MultiTerminal. This guide explains what you'll see, how to manage your MCP servers, and how to bring your existing MCPs under one roof.
What is MCP?
MCP servers give Claude Code agents tools — the ability to do things beyond just generating text. Through MCP, agents can create tasks, send messages, search code, manage databases, and interact with external services.
Think of MCP servers as plugins for Claude Code. Each server provides a set of tools that agents can call. MultiTerminal ships with two MCP servers that give agents full access to the MultiTerminal platform.
New to MCP? You can skip the “Your Existing MCPs” and “Importing MCPs” sections below — the two built-in servers work out of the box with no configuration. Come back to them only when you want to bring your own MCP servers under one roof.
What You See After Installation
After installing MultiTerminal, open a terminal and run /mcp in Claude Code. You'll see something like this:
Your exact list will differ — the servers above the divider are whatever you already had configured. The point is that the two MultiTerminal built-ins (mcp-gateway and multiterminal) appear at the bottom.
Manage MCP servers
5 servers
your-existing-mcp-1 - connected
your-existing-mcp-2 - connected
your-existing-mcp-3 - connected
Built-in MCPs (always available)
mcp-gateway - connected
multiterminal - connectedYour existing MCPs are unchanged — they still work exactly as before. MultiTerminal adds two new servers below them.
The two MultiTerminal servers are loaded automatically whenever you open a terminal through MultiTerminal. They won't appear in standalone Claude Code sessions outside of MultiTerminal.
The Two Built-in Servers
| Server | Purpose | Example Tools |
|---|---|---|
| multiterminal | Core tools for tasks, messaging, code search, browser tabs, projects, and team coordination | list_tasks, send_message, search_code, open_browser_tab |
| mcp-gateway | MCP proxy and manager — aggregates tools from other MCP servers and provides server/profile management | gateway__list_servers, gateway__add_server, gateway__set_profile |
The multiterminal server is what agents use day-to-day — managing tasks, sending messages, searching your codebase. See the MCP Tools Reference for the full list of ~90 tools.
The mcp-gateway server is your MCP management layer. It acts as a proxy: you register other MCP servers with the gateway, and it aggregates all their tools into a single connection. This gives you centralized control over which servers are active, organized by profiles.
Your Existing MCPs
If you already have MCP servers configured in Claude Code (in your ~/.claude.json or project-level .mcp.json files), they continue to work alongside MultiTerminal's servers. Nothing changes about your existing setup.
Over time, you can choose to import your existing MCPs into the gateway. This is optional but gives you benefits:
- Centralized management — enable/disable servers without editing JSON files
- Profiles — switch between different server sets for different projects
- Visibility — see all your MCP servers and their status in one place
- Reliability — the gateway handles crash recovery and automatic reconnection
Importing MCPs into the Gateway
To bring your existing MCPs under gateway management, use the import tools from any Claude Code terminal:
Import from Claude Code config
This reads your ~/.claude.json and imports all MCP servers found there:
gateway__import_claude_config()Import from an .mcp.json file
Point to any .mcp.json file to import its servers:
gateway__import_mcp_config(configPath="C:/path/to/.mcp.json")Importing is non-destructive — it copies server configurations into the gateway database. Your original config files are not modified. You can remove the originals later once you've confirmed everything works through the gateway.
Managing Servers
Once servers are registered with the gateway, you can manage them using these tools:
| Tool | What It Does |
|---|---|
gateway__list_servers |
Show all registered servers with connection status |
gateway__add_server |
Register a new MCP server (name, command, args) |
gateway__remove_server |
Unregister a server |
gateway__enable_server |
Enable a disabled server (starts it up) |
gateway__disable_server |
Disable a server without removing it |
Adding a server manually
gateway__add_server(
name="my-database-mcp",
command="npx",
args=["-y", "@my-org/database-mcp"],
env={"DB_URL": "postgresql://localhost/mydb"}
)Using Profiles
Profiles let you define sets of servers for different contexts. For example, you might have a "web-dev" profile with database and API servers, and a "data-science" profile with notebook and visualization servers.
| Tool | What It Does |
|---|---|
gateway__list_profiles |
Show all profiles and which is active |
gateway__create_profile |
Create a new profile with selected servers |
gateway__set_profile |
Switch the active profile (connects/disconnects servers as needed) |
gateway__delete_profile |
Remove a profile |
A default profile is created automatically and includes all registered servers. You can create additional profiles to customize which servers are available per project.
MultiTerminal can automatically switch gateway profiles when you open different projects. Configure this in the project settings under MCP Servers.
Troubleshooting
MCP servers not showing up
Make sure you're running Claude Code from within a MultiTerminal terminal. The MCP servers are loaded via the --mcp-config flag, which MultiTerminal sets automatically when launching terminals.
Gateway shows "disconnected"
Check that .NET 8 Runtime is installed. The gateway is a .NET application and requires the runtime. Run dotnet --list-runtimes to verify.
Imported server won't connect
Verify the server's command is available on your PATH. Use gateway__list_servers to check the connection status and error messages. The gateway retries failed connections automatically (up to 3 attempts with exponential backoff).
Want to debug gateway output
Set the environment variable MCP_GATEWAY_DEBUG=1 to enable stderr logging from the gateway process.