| name | mcporter-serve-setup |
| description | Install, start, and configure mcporter-serve, the shared per-server MCP gateway. Use when setting it up for the first time, importing existing MCP servers from Claude/Codex/Cursor, starting or restarting the daemon and serve bridge, wiring per-server endpoints into a client, or debugging why an endpoint is down.
Triggers: - "set up mcporter-serve" / "install the mcp gateway" - "import my mcp servers" - "start / restart the mcporter daemon" - "wire per-server mcp endpoints into claude" - "why isn't the serve endpoint responding"
|
mcporter-serve setup
A single daemon hosts your MCP servers; mcporter serve exposes that fleet over HTTP so
every agent shares one copy of each server instead of spawning its own. This skill installs
it, imports the servers you already have, starts the gateway, and points your agents at it.
1. Install
git clone https://github.com/zm2231/mcporter-serve && cd mcporter-serve
./install.sh
On macOS this builds, installs mcporter globally, copies these skills into
~/.claude/skills, and registers a launchd agent (com.mcporter.serve) that keeps serve
alive on port 4748. On Linux/Windows it installs and prints the command to run serve yourself.
2. Import the servers you already have
Do not hand-write ~/.mcporter/mcporter.json. First ask the user which source to import
from, since most people have servers defined in more than one tool:
"Where should I import your MCP servers from? I can read Claude Code, Claude Desktop,
Codex, Cursor, VS Code, Windsurf, or OpenCode."
Then preview that source before writing anything (no --copy lists without changing config):
mcporter config import claude
Show the user the discovered servers, confirm which to keep, then copy them in. Use
--filter to narrow, --copy to write:
mcporter config import codex --copy
mcporter config import claude --filter notion --copy
Repeat per source. Imported definitions land in ~/.mcporter/mcporter.json, which is the
one place servers are defined from now on.
3. Start and control the gateway
Two pieces: the daemon owns the running server fleet; serve is the HTTP bridge in
front of it. The daemon self-spawns on the first tool call, but you can drive it directly.
mcporter daemon status
mcporter daemon start
mcporter daemon restart
mcporter daemon stop
Restart the serve bridge (macOS launchd):
launchctl kickstart -k "gui/$(id -u)/com.mcporter.serve"
If the agent ever isn't loaded:
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.mcporter.serve.plist"
Without launchd (Linux/Windows or manual runs):
mcporter serve --http 4748
4. Point your agents at it
Per-server is the default: one entry per server, unprefixed tool names. For Claude, add to
~/.claude.json:
{ "type": "http", "url": "http://127.0.0.1:4748/mcp/<server>" }
Aggregate (everything behind one entry, tools namespaced mcporter__<server>__<tool>):
{ "type": "http", "url": "http://127.0.0.1:4748/mcp" }
After editing client config, reload the client (in Claude: /reload-plugins then /mcp).
5. Verify
mcporter list <server>
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:4748/mcp/<server> \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
Troubleshooting
| Symptom | Fix |
|---|
| Port 4748 refuses connections | serve isn't running. launchctl kickstart -k "gui/$(id -u)/com.mcporter.serve", or mcporter serve --http 4748 |
| Endpoint returns 404 for a real server | not in mcporter.json yet, or daemon stale. Import/add it, then mcporter daemon restart |
Server missing from mcporter daemon status | mcporter daemon restart |
| Tools don't appear in the client | reload the client after config edits (Claude: /reload-plugins) |
| stdio server fails only under launchd | PATH issue. The plist's PATH must include your node bin dir; check ~/Library/Logs/mcporter-serve.log |
See skills/manage-mcp for adding, removing, and debugging individual servers.
