Using with Claude Desktop

Connect Claude Desktop to your MCP Gateway and access all your servers through a single configuration.

Why Use MCP Gateway with Claude Desktop?

Instead of configuring each MCP server individually in Claude Desktop, you can point it to your MCP Gateway and get:

  • Single configuration - One endpoint for all your servers
  • Centralized management - Add/remove servers from the console without editing config files
  • Server aggregation - All tools from all servers available in one place
  • Usage tracking - See which tools are being used in the console

Configuration

1

Locate Your Config File

Claude Desktop stores its configuration in a JSON file. The location depends on your operating system:

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json
# Windows
%APPDATA%\Claude\claude_desktop_config.json
# Linux
~/.config/Claude/claude_desktop_config.json
2

Add the Gateway Configuration

Add the MCP Gateway to your mcpServers configuration. Since Claude Desktop uses stdio transport, we use mcp-remote to bridge to the gateway's HTTP endpoint: 

{
  "mcpServers": {
    "appxen": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your appliance address>/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your API key>" }
    }
  }
}

Self-signed certificate: until the appliance has a domain it serves a self-signed certificate, which mcp-remote (Node.js) rejects, so Claude Desktop cannot connect. Set DomainName at launch, or point a domain's DNS A record at the ElasticIp output and run sudo appxenctl set-domain <name> on the instance, before you add this entry.

Note: replace <your API key> with an API key from the console (create one under API Keys, in the General section of the sidebar; it starts with axgw_ and is shown once). There is no OAuth sign-in: the key is the only credential.

Header: type Authorization:${AUTH_HEADER} exactly as shown, with no space after the colon. mcp-remote fills in AUTH_HEADER from env, and some clients split an argument that contains a space.

Requires: Node.js installed on your system. The mcp-remote package will be automatically downloaded on first use.

3

Restart Claude Desktop

After saving the configuration file, restart Claude Desktop for the changes to take effect. You should see your connected servers' tools available in Claude.

Full Configuration Example

Here's a complete example with the gateway alongside other local MCP servers: 

{
  "mcpServers": {
    "appxen": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your appliance address>/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your API key>" }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    }
  }
}

Claude Code and Cursor

Cursor uses the same entry in ~/.cursor/mcp.json. Claude Code connects directly, with one command: 

claude mcp add --transport http appxen "https://<your appliance address>/mcp" --header "Authorization: Bearer <your API key>"

More on connecting clients, including the other endpoints, in Connect an MCP client.

Verifying the Connection

Once configured, you can verify the connection is working by:

  1. Opening a new conversation in Claude Desktop
  2. Asking Claude to list available tools
  3. You should see tools from all your connected servers (e.g., github__get_me)

Try asking:

"What tools do you have available from my connected MCP servers?"

Troubleshooting

"command" Required error?

If you see an error like invalid_type: expected "string" for "command", you're using the wrong config format.

  • Claude Desktop requires stdio transport (command + args), not direct URLs
  • Use the mcp-remote bridge as shown in the configuration above
  • Make sure you have Node.js installed for npx to work

Tools not appearing?

  • Check that your API key is correct
  • Verify you have at least one server enabled in the console
  • Ensure Claude Desktop was fully restarted after config changes

Added or removed servers but don't see changes?

Claude Desktop caches the tools list at startup. After adding, removing, or enabling/disabling servers in the console:

  • Restart Claude Desktop to refresh the tools list
  • On macOS: Quit Claude (Cmd+Q), then reopen
  • On Windows: Close Claude completely, then reopen

Connection errors?

  • Check that your computer can reach the appliance's address (the security group lets the whole internet reach ports 80 and 443)
  • Verify the URL is exactly https://<your appliance address>/mcp
  • If the appliance has no domain yet, it serves a self-signed certificate that mcp-remote rejects: give it a domain (see the note above)
  • Make sure your API key hasn't been revoked

JSON syntax errors?

  • Ensure all strings are in double quotes
  • Check for trailing commas (not allowed in JSON)
  • Use a JSON validator to check your config file

What's Next?