Version: 1.1.x

Connect your client to MCPX

Choose a client to jump to its MCPX setup:

Cursor

Connect Cursor to MCPX.

{
  "mcpServers": {
    "mcpx": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Instructions

In Cursor, go to Settings → Cursor Settings → Tools & MCP.
Click Add Custom MCP to open ~/.cursor/mcp.json.
Add the MCPX connection using the JSON on the left.
Under Tools & MCP, you should see MCPX under MCP tools.

Note: If MCPX tools do not respond, turn the MCPX server off and on again in Tools & MCP to reconnect - no need to quit Cursor.

Claude Code

Connect Claude Code to MCPX.

claude mcp add --transport http mcpx http://localhost:9000/mcp --scope user

Instructions

Open a terminal.
Run the command on the left to register MCPX.
Close and reopen Claude Code in the terminal.
Run /mcp and confirm MCPX; use Authenticate if needed.
You should see mcpx in Claude Code’s MCP list and the agent in the MCPX UI.

VS Code

Connect VS Code to MCPX.

{
  "servers": {
    "mcpx": {
      "url": "http://localhost:9000/mcp",
      "type": "http"
    }
  }
}

Instructions

Open .vscode/mcp.json.
Click Add server, choose HTTP, and paste your MCPX /mcp URL.
Rename the default server id to mcpx.
Click Start for mcpx.

Important: Restart VS Code so MCPX tools load reliably.

Warp

Connect Warp to MCPX.

{
  "mcpx": {
    "serverUrl": "http://localhost:9000/mcp"
  }
}

Instructions

Open Warp Settings from the command palette.
Go to Agents → MCP Servers.
Click Add +, or open an existing mcpx entry and use + to update.
Paste the MCPX JSON from the left.
Click Save.

Codex Desktop

Connect Codex Desktop to MCPX.

[mcp_servers.mcpx]
enabled = true
url = "http://localhost:9000/mcp"

Instructions

Option 1 - config file

Settings → Settings → Configuration.
Open config.toml (.codex/config.toml) and add the MCPX block from the left.
Save and restart Codex.

Option 2 - MCP Servers UI

Settings → MCP Servers → Add Server.
Streamable HTTP, Name mcpx, URL http://localhost:9000/mcp.
Save.

Important: Restart Codex after changes. If Codex does not appear in MCPX, ask Codex which MCP tools are connected.

Claude Desktop

Connect Claude Desktop to MCPX.

{
  "mcpServers": {
    "mcpx": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.36",
        "http://localhost:9000/mcp"
      ]
    }
  }
}

Instructions

In Claude Desktop, go to Settings → Developer.
Click Edit Config and open claude_desktop_config.json.
Merge in the MCPX JSON from the left, then save.
Restart Claude Desktop so MCPX tools load.

Important: Restart Claude after saving so MCPX integrations initialize correctly.

n8n

Connect n8n to MCPX.

Instructions

Use the MCP Client node. If MCPX shows an n8n-specific JSON snippet for your version, prefer that.

Open your workflow and add a node (+).
Search mcp client and add it.
Server Transport: HTTP Streamable. MCP Endpoint URL: http://localhost:9000/mcp. Authentication: MCP OAuth2.
Create MCP OAuth2 API credentials: Server URL http://localhost:9000/mcp, Allowed HTTP Request Domains All, then authorize.
Choose a Tool allowed by MCPX.

GitHub Copilot

Connect GitHub Copilot to MCPX.

{
  "servers": {
    "mcpx": {
      "url": "http://localhost:9000/mcp",
      "type": "http"
    }
  }
}

Instructions

The in-product flow is labeled Connect with VS Code; it matches VS Code MCPX setup.

Open .vscode/mcp.json.
Add server → HTTP → paste the MCPX URL.
Rename the server to mcpx and Start it.

Important: Restart VS Code if MCPX tools do not appear.

ChatGPT

Connect ChatGPT to MCPX.

Instructions

In chatgpt.com, open Apps.
Enable Developer mode under Settings → Apps → Advanced settings.
Click Create app.
Set Name to MCPX, MCP Server URL to http://localhost:9000/mcp, Authentication to OAuth (on).
Click Create.

You should see the app in ChatGPT and can route conversations through MCPX.

Custom MCP SDK

MCPX is an MCP server like any other, but it is remote-first (typically HTTPS in production). Clients should use Streamable HTTP to the /mcp endpoint, or SSE on /sse for legacy compatibility - not stdio.

Set MCPX_HOST to your MCPX origin (for example http://localhost:9000). You can pass extra headers on the transport (for example x-lunar-consumer-tag) for routing and policy; see Basic API Key Authorization and the Access Control List for header and ACL patterns.

Streamable HTTP (recommended)

const transport = new StreamableHTTPClientTransport(
  new URL(`${MCPX_HOST}/mcp`),
  {
    requestInit: {
      headers: {
        "x-lunar-consumer-tag": "my_agent_name",
      },
    },
  }
);

SSE (deprecated path; MCPX still supports it)

const transport = new SSEClientTransport(new URL(`${MCPX_HOST}/sse`), {
  eventSourceInit: {
    fetch: (url, init) => {
      const headers = new Headers(init?.headers);
      const consumerTag = "my_agent_name";
      headers.set("x-lunar-consumer-tag", consumerTag);
      return fetch(url, { ...init, headers });
    },
  },
});

Connect the MCP client

const client = new Client({ name: "mcpx-client", version: "1.0.0" });
await client.connect(transport);

Remote MCPX over HTTP

Open-source MCPX often runs locally without TLS. Browsers and some stacks block plain HTTP by default. To point mcp-remote at a remote non-TLS MCPX instance, start it with --allow-http and pin the mcp-remote version your deployment supports (for example mcp-remote@0.1.36).

For security, prefer exposing MCPX inside your VPC or over TLS rather than raw HTTP on the public internet.

Example: Claude Desktop via mcp-remote to remote HTTP MCPX
{
  "mcpServers": {
    "mcpx": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.36",
        "http://localhost:9000/mcp",
        "--allow-http",
        "--header",
        "x-lunar-consumer-tag: Claude"
      ]
    }
  }
}

MCPX demo client

If you do not yet have a preferred client, use the MCPX demo client in the Lunar repo. It demonstrates an end-to-end path to MCPX with an LLM (Gemini or Claude).

From the mcpx/demo-client directory:

cd demo-client
npm install

The demo uses an LLM API key:

# Gemini
GEMINI_API_KEY=<your-key> npm run start:gemini

# Claude
ANTHROPIC_API_KEY=<your-key> npm run start:claude

You can also set variables in ./demo-client/.env. See the demo source for more options.

Supported agents at a glance

Agent / integration	Config format	Transport	Auth
Cursor	JSON (`~/.cursor/mcp.json`)	Streamable HTTP (`/mcp`)	MCPX OAuth / deployment-specific
Claude Code	CLI (`claude mcp add`)	HTTP	MCPX OAuth when prompted
VS Code	JSON (`.vscode/mcp.json`)	HTTP	MCPX OAuth / deployment-specific
Warp	JSON (Warp MCP servers)	HTTP	MCPX OAuth / deployment-specific
Codex Desktop	TOML (`.codex/config.toml`) or UI	Streamable HTTP	MCPX OAuth / deployment-specific
Claude Desktop	JSON (`claude_desktop_config.json`)	`mcp-remote` → HTTP	MCPX OAuth / deployment-specific
n8n	MCP Client node	HTTP Streamable	MCP OAuth2 to MCPX
GitHub Copilot	JSON (`.vscode/mcp.json`)	HTTP	MCPX OAuth / deployment-specific
ChatGPT	ChatGPT Apps UI	HTTP	OAuth (per app)
Custom MCP SDK	Your application code	Streamable HTTP (recommended) or SSE	MCPX + optional headers (API keys, ACL)
Remote MCPX over HTTP	JSON + `mcp-remote`	HTTP (`--allow-http`)	As configured on MCPX
MCPX demo client	Env + npm scripts	HTTP to MCPX	LLM API key (Gemini / Claude)

Cursor

Instructions​

Claude Code

Instructions​

VS Code

Instructions​

Warp

Instructions​

Codex Desktop

Instructions​

Claude Desktop

Instructions​

n8n

Instructions​

GitHub Copilot

Instructions​

ChatGPT

Instructions​

Custom MCP SDK

Streamable HTTP (recommended)​

SSE (deprecated path; MCPX still supports it)​

Connect the MCP client​

Remote MCPX over HTTP

MCPX demo client

Supported agents at a glance​

Instructions

Instructions

Instructions

Instructions

Instructions

Instructions

Instructions

Instructions

Instructions

Streamable HTTP (recommended)

SSE (deprecated path; MCPX still supports it)

Connect the MCP client

Supported agents at a glance