Connecting your MCP clients to MCP Gateway

You can connect the following MCP clients with MCP Gateway:

Cursor
Claude Code
VS Code
Warp
Codex Desktop
Claude Desktop
n8n
GitHub Copilot
ChatGPT
Custom MCP SDK
Remote MCP Gateway over HTTP
MCP Gateway demo client

Cursor

Connect Cursor to MCP Gateway.

{
  "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 MCP Gateway connection using the JSON configuration shown above.
Confirm that MCP Gateway appears under Tools & MCP.

note

If MCP Gateway tools do not respond, turn the MCP Gateway server off and on again in Tools & MCP to reconnect. You do not need to quit Cursor.

Claude Code

Connect Claude Code to MCP Gateway.

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

Instructions:

Open a terminal.
Run the command above to register MCP Gateway.
Close and reopen Claude Code in the terminal.
Run /mcp and confirm MCP Gateway appears. Select Authenticate if prompted.
Confirm that mcpx appears in Claude Code's MCP list and the agent in the MCP Gateway UI.

VS Code

Connect VS Code to MCP Gateway.

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

Instructions:

Open .vscode/mcp.json.
Click Add server, choose HTTP, and paste your MCP Gateway /mcp URL.
Rename the default server id to mcpx.
Click Start for mcpx.
Restart VS Code so MCP Gateway tools load reliably.

Warp

Connect Warp to MCP Gateway.

{
  "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 click + to update it.
Paste the MCP Gateway JSON above.
Click Save.

Codex Desktop

Connect Codex Desktop to MCP Gateway.

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

Instructions:

Option 1: Config file

Go to Settings → Settings → Configuration.
Open config.toml (.codex/config.toml) and add the MCP Gateway block above.
Save and restart Codex.

Option 2: MCP Servers UI

Go to Settings → MCP Servers → Add Server.
Select Streamable HTTP, and do the following:
1. For Name, enter mcpx.
2. For URL, enter http://localhost:9000/mcp.
Click Save.
Restart Codex. If Codex does not appear in MCP Gateway, ask Codex which MCP tools are connected.

Claude Desktop

Connect Claude Desktop to MCP Gateway.

{
  "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 MCP Gateway JSON shown above, then save the file.
Restart Claude Desktop so MCP Gateway tools load.
Restart Claude after saving so MCP Gateway integrations initialize correctly.

n8n

Connect n8n to MCP Gateway.

Instructions:

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

Open your workflow and click + to add a node.
Search MCP Client and add it.
Set the following:
1. Server Transport to HTTP Streamable.
2. MCP Endpoint URL to http://localhost:9000/mcp.
3. Authentication to MCP OAuth2.
Do the following to create MCP OAuth2 API credentials:
1. Set Server URL to http://localhost:9000/mcp.
2. Set Allowed HTTP Request Domains to All. Then, authorize.
Select a tool allowed by MCP Gateway.

GitHub Copilot

Connect GitHub Copilot to MCP Gateway.

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

Instructions:

The in-product flow is labeled Connect with VS Code and follows the same steps as the VS Code MCP Gateway setup.

Open .vscode/mcp.json.
Click Add server → HTTP. Then, paste the MCP Gateway URL.
Rename the server to mcpx. Then, click Start.
Restart VS Code if MCP Gateway tools do not appear.

ChatGPT

Connect ChatGPT to MCP Gateway.

Instructions:

In ChatGPT, 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, and Authentication to OAuth (on).
Click Create.

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

Custom MCP SDK

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

Set MCPX_HOST to your MCP Gateway origin. For example, http://localhost:9000. You can pass extra headers on the transport, for example, x-lunar-consumer-tag for routing and policy. Refer to Basic API key authorization and 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; MCP Gateway 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 MCP Gateway over HTTP

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

note

For security, prefer exposing MCP Gateway inside your VPC or over TLS instead of 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"
      ]
    }
  }
}

MCP Gateway demo client

If you do not yet have a preferred client, use the MCP Gateway demo client in the Lunar repository. It demonstrates an end-to-end path to MCP Gateway with an LLM, such as 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. Refer to 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`)	MCP Gateway OAuth / deployment-specific
Claude Code	CLI (`claude mcp add`)	HTTP	MCP Gateway OAuth when prompted
VS Code	JSON (`.vscode/mcp.json`)	HTTP	MCP Gateway OAuth / deployment-specific
Warp	JSON (Warp MCP servers)	HTTP	MCP Gateway OAuth / deployment-specific
Codex Desktop	TOML (`.codex/config.toml`) or UI	Streamable HTTP	MCP Gateway OAuth / deployment-specific
Claude Desktop	JSON (`claude_desktop_config.json`)	`mcp-remote` → HTTP	MCP Gateway OAuth / deployment-specific
n8n	MCP Client node	HTTP Streamable	MCP OAuth2 to MCP Gateway
GitHub Copilot	JSON (`.vscode/mcp.json`)	HTTP	MCP Gateway OAuth / deployment-specific
ChatGPT	ChatGPT Apps UI	HTTP	OAuth (per app)
Custom MCP SDK	Your application code	Streamable HTTP (recommended) or SSE	MCP Gateway + optional headers (API keys, ACL)
Remote MCP Gateway over HTTP	JSON + `mcp-remote`	HTTP (`--allow-http`)	As configured on MCP Gateway
MCP Gateway demo client	Env + npm scripts	HTTP to MCP Gateway	LLM API key (Gemini / Claude)