Managing MCP Servers

OXP as a Universal MCP Router

OXP is not just an extension protocol — it is the fastest way to wire MCP servers into every AI-aware IDE on your machine simultaneously.

Instead of editing JSON config files for VS Code, Cursor, Windsurf, and Claude Desktop separately, you run one command and OXP injects the server configuration into all of them automatically.

oxp install @modelcontextprotocol/server-github

That single command:

1. Fetches the server spec from the OXP registry
2. Detects every installed AI client (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Desktop)
3. Merges the launcher entry into each client's config file, atomically
4. Probes the server with a live MCP initialize handshake and reports reachability

Sample output:

✓ MCP install: @modelcontextprotocol/server-github
  launcher: npx -y @modelcontextprotocol/server-github
  clients:
    - Claude Desktop        — installed ✓
    - Cursor                — installed ✓
    - VS Code (Copilot)     — installed ✓
  verified reachable ✓
  restart the affected client(s) to load the new server.
  log: ~/.oxp/logs/mcp-install.jsonl

---

Installing MCP Servers

From the OXP Registry

oxp install @modelcontextprotocol/server-github
oxp install @modelcontextprotocol/server-filesystem
oxp install @upstash/context7-mcp

From a deep link

oxp install --from oxp://mcp/github

Browse the full library

Open the MCP Library in your browser and click Install on any server.

---

How Auto-Injection Works

OXP writes the server config into the standard config location each client expects. The write is atomic — a temporary file is written then renamed — so you never get a partially-written config, even if the process is interrupted.

On Windows, Application Support paths map to %APPDATA%\Roaming. On Linux, they follow XDG ($XDG_CONFIG_HOME or ~/.config/).

OXP only writes to a client whose parent config directory already exists — you won't get a stale config entry for a client you don't have installed.

---

Reachability Verification

After injecting the config, OXP spawns the server process and runs a live MCP initialize handshake (8-second timeout). The result is shown inline and written to the log:

  verified reachable ✓

or, if something is wrong:

  not reachable: timed out — server did not respond to initialize (may need credentials)
  (server is configured — check credentials or restart client)

The server is still configured even when the probe fails — most probe failures are credential issues (the server crashes immediately when YOUR_API_KEY is missing), not installation problems. Set the required env vars in the client's settings UI after installing, then the server will start cleanly.

---

Install Logs

Every install, update, and probe operation appends a JSON line to ~/.oxp/logs/mcp-install.jsonl:

{"ts":"2025-05-14T10:00:00Z","kind":"install","id":"@modelcontextprotocol/server-github","client":"claude-desktop","status":"ok"}
{"ts":"2025-05-14T10:00:00Z","kind":"install","id":"@modelcontextprotocol/server-github","client":"cursor","status":"ok"}
{"ts":"2025-05-14T10:00:00Z","kind":"probe","id":"@modelcontextprotocol/server-github","status":"reachable"}

The log is append-only, written with mode 0600 in a 0700 directory — readable only by your user. It is the first place to look when something goes wrong.

---

Removing a Server

oxp mcp rollback @modelcontextprotocol/server-github

This removes the server entry from every detected client's config file — the exact inverse of oxp install. OXP touches only the server's own key; no other config is modified or removed.

Sample output:

oxp mcp rollback: @modelcontextprotocol/server-github
  ✓ removed from Claude Desktop    ~/Library/Application Support/Claude/claude_desktop_config.json
  ✓ removed from Cursor            ~/.cursor/mcp.json
  · VS Code (Copilot) — not configured
  restart the affected client(s) to apply the change.
  log: ~/.oxp/logs/mcp-install.jsonl

Use --json for machine-readable output (useful in scripts):

oxp mcp rollback @modelcontextprotocol/server-github --json

---

Checking Server Health

oxp doctor — MCP section

oxp doctor includes a dedicated MCP section. It reads every detected client's config, deduplicates server specs by launcher command, and probes each unique server in parallel (bounded at 8 s per server):

MCP servers:
  Claude Desktop  (~/Library/Application Support/Claude/claude_desktop_config.json)
    • server-github                  reachable ✓
    • server-filesystem              not reachable — timed out (may need credentials)
  Cursor  (~/.cursor/mcp.json)
    • server-github                  reachable ✓

oxp doctor         # human-readable with MCP section
oxp doctor --json  # machine-readable; includes a top-level `mcp` array

The --json output shape for the MCP section:

{
  "mcp": [
    {
      "id": "claude-desktop",
      "name": "Claude Desktop",
      "configPath": "~/Library/Application Support/Claude/claude_desktop_config.json",
      "servers": [
        { "slug": "server-github", "command": "npx", "args": [...], "reachable": true }
      ]
    }
  ]
}

---

Troubleshooting