> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting AI Clients

> How to configure Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, and OpenAI Playground.

## Finding Your Server URL

Every GetMCP server has a unique MCP endpoint URL. Find it by:

1. Going to **GetMCP > Dashboard**
2. Clicking on your server
3. Copying the **Server URL** shown at the top of the server detail page

The URL format is:

```text theme={null}
https://yoursite.com/mcp/{slug}
```

<img src="https://mintcdn.com/infiwebs/X3D8lQwdysxDpY3z/images/server-url.png?fit=max&auto=format&n=X3D8lQwdysxDpY3z&q=85&s=143d0e37cd178c48a1e39887db9321ad" alt="Server URL" width="1314" height="287" data-path="images/server-url.png" />

<Note>
  Authentication in your MCP client config serves two purposes: **(1)** sending an access token if your server has inbound authentication enabled, and/or **(2)** supplying your own API credentials that GetMCP forwards to external APIs when tools run. The method differs per client — Claude Desktop uses `--header` args; Cursor, Windsurf, and VS Code use a `headers` JSON object. See [Authentication](/docs/guides/authentication) for a full explanation.
</Note>

***

## Claude Desktop

<Note>
  **Requires:** Claude Desktop app installed · Node.js 18+ installed (needed for `mcp-remote`)
</Note>

<Steps>
  <Step title="Open Claude Desktop">
    Open the Claude Desktop app.
  </Step>

  <Step title="Open Developer Settings and click Edit Config">
    * **macOS:** Menu bar → Claude → Settings → Developer → Edit Config
    * **Windows:** Breadcrumb menu (top bar) → File → Settings → Developer → Edit Config

    The config file opens in a text editor. It is located at:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  </Step>

  <Step title="Copy the configuration below and paste it into the mcpServers object, then save">
    **No authentication (macOS / Linux):**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://yoursite.com/mcp/my-server"
          ]
        }
      }
    }
    ```

    **No authentication (Windows)** — routes through `cmd.exe` to avoid Node.js path-with-spaces issues:

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "cmd",
          "args": [
            "/c",
            "npx",
            "mcp-remote",
            "https://yoursite.com/mcp/my-server"
          ]
        }
      }
    }
    ```

    If your server has inbound authentication enabled, pass the credential as a `--header` arg (no space after the colon). On Windows, use `cmd /c npx` as shown above and add the `--header` args the same way.

    **Bearer token:**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://yoursite.com/mcp/my-server",
            "--header",
            "Authorization:Bearer YOUR_BEARER_TOKEN"
          ]
        }
      }
    }
    ```

    **Basic auth** (base64-encode `username:password` first):

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://yoursite.com/mcp/my-server",
            "--header",
            "Authorization:Basic BASE64_USERNAME_PASSWORD"
          ]
        }
      }
    }
    ```

    **API key (header):**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://yoursite.com/mcp/my-server",
            "--header",
            "X-API-Key:YOUR_API_KEY"
          ]
        }
      }
    }
    ```

    **API key (query param) or OAuth:** Use the plain URL — no `--header` needed. For query-param keys, append `?keyName=YOUR_KEY` to the URL. OAuth opens a browser flow automatically.
  </Step>

  <Step title="Fully quit and restart Claude Desktop">
    Closing the window is not enough — fully quit and relaunch. The server will appear in the MCP panel.
  </Step>
</Steps>

<Note>
  Fully quit and restart Claude Desktop after saving — closing the window is not enough.
</Note>

[Claude Desktop MCP docs](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

***

## Claude Code

<Note>
  **Requires:** Claude Code CLI installed — `npm install -g @anthropic-ai/claude-code`
</Note>

<Steps>
  <Step title="Open your terminal">
    Open your terminal.
  </Step>

  <Step title="Copy and run the command below">
    **No authentication:**

    ```bash theme={null}
    claude mcp add --transport http my-server https://yoursite.com/mcp/my-server
    ```

    **Bearer token:**

    ```bash theme={null}
    claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
      --header "Authorization: Bearer YOUR_BEARER_TOKEN"
    ```

    **Basic auth** (base64-encode `username:password` first):

    ```bash theme={null}
    claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
      --header "Authorization: Basic BASE64_USERNAME_PASSWORD"
    ```

    **API key (header):**

    ```bash theme={null}
    claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
      --header "X-API-Key: YOUR_API_KEY"
    ```

    **API key (query param) or OAuth:** Use the plain URL — no `--header` needed. For query-param keys, append `?keyName=YOUR_KEY` to the URL.

    Other useful commands:

    ```bash theme={null}
    # List all connected MCP servers
    claude mcp list

    # Remove a server
    claude mcp remove my-server
    ```
  </Step>

  <Step title="Claude Code confirms the server was added immediately">
    The server is registered right away — no restart needed.
  </Step>

  <Step title="Run /mcp inside Claude Code to verify the server appears">
    Type `/mcp` in Claude Code to confirm the server is listed and connected.
  </Step>
</Steps>

<Note>
  The server is added immediately — no restart needed.
</Note>

[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)

***

## Cursor

<Note>
  **Requires:** Cursor editor installed
</Note>

<Steps>
  <Step title="Open Cursor and go to Settings">
    Open Cursor and go to **Settings**.
  </Step>

  <Step title="Navigate to Tools & MCP, then click Add a custom MCP">
    Navigate to **Tools & MCP**, then click **Add a custom MCP**.
  </Step>

  <Step title="The mcp.json file opens in the editor">
    The `mcp.json` config file opens in the editor automatically.
  </Step>

  <Step title="Copy the configuration below, paste it into the mcpServers object, then save">
    **No authentication:**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "url": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    If your server has inbound authentication enabled, add a `headers` object before `url`:

    **Bearer token:**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "Authorization": "Bearer YOUR_BEARER_TOKEN"
          },
          "url": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **Basic auth** (base64-encode `username:password` first):

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "Authorization": "Basic BASE64_USERNAME_PASSWORD"
          },
          "url": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **API key (header):**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "X-API-Key": "YOUR_API_KEY"
          },
          "url": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **API key (query param) or OAuth:** No `headers` needed — use the plain URL. For query-param keys, append `?keyName=YOUR_KEY` to the URL.

    **File location:** `~/.cursor/mcp.json` (global) · `.cursor/mcp.json` (project)
  </Step>
</Steps>

<Note>
  Restart Cursor after saving to apply the changes.
</Note>

[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol)

***

## Windsurf

<Note>
  **Requires:** Windsurf editor installed
</Note>

<Steps>
  <Step title="Open Windsurf and go to Settings">
    Open Windsurf and go to **Settings**.
  </Step>

  <Step title="Click on Cascade, then click Open MCP Registry">
    Click on **Cascade**, then click **Open MCP Registry**.
  </Step>

  <Step title="The mcp_config.json file opens in the editor">
    The `mcp_config.json` config file opens in the editor automatically.
  </Step>

  <Step title="Copy the configuration below and paste it into the mcpServers object, then save">
    **No authentication:**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "serverUrl": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    If your server has inbound authentication enabled, add a `headers` object before `serverUrl`:

    **Bearer token:**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "Authorization": "Bearer YOUR_BEARER_TOKEN"
          },
          "serverUrl": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **Basic auth** (base64-encode `username:password` first):

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "Authorization": "Basic BASE64_USERNAME_PASSWORD"
          },
          "serverUrl": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **API key (header):**

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "headers": {
            "X-API-Key": "YOUR_API_KEY"
          },
          "serverUrl": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    **API key (query param) or OAuth:** No `headers` needed — use the plain URL. For query-param keys, append `?keyName=YOUR_KEY` to the URL.

    **File location:** `~/.codeium/windsurf/mcp_config.json`
  </Step>
</Steps>

<Note>
  Restart Windsurf after saving to apply the changes.
</Note>

[Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)

***

## VS Code

<Note>
  **Requires:** VS Code with GitHub Copilot extension installed · Agent mode enabled: VS Code Settings → search "chat agent" → enable
</Note>

<Steps>
  <Step title="Open (or create) .vscode/mcp.json in your project root">
    Open (or create) `.vscode/mcp.json` in your project root.

    For a global config, open the Command Palette and run **MCP: Open User Configuration**.
  </Step>

  <Step title="Copy the configuration below and paste it into the file">
    **No authentication:**

    ```json theme={null}
    {
      "servers": {
        "my-server": {
          "type": "http",
          "url": "https://yoursite.com/mcp/my-server"
        }
      }
    }
    ```

    If your server has inbound authentication enabled, add a `headers` object. VS Code's `${input:}` syntax prompts you to enter the value securely on first use:

    **Bearer token:**

    ```json theme={null}
    {
      "servers": {
        "my-server": {
          "type": "http",
          "url": "https://yoursite.com/mcp/my-server",
          "headers": {
            "Authorization": "Bearer ${input:my-server-key}"
          }
        }
      }
    }
    ```

    **Basic auth:**

    ```json theme={null}
    {
      "servers": {
        "my-server": {
          "type": "http",
          "url": "https://yoursite.com/mcp/my-server",
          "headers": {
            "Authorization": "Basic ${input:my-server-key}"
          }
        }
      }
    }
    ```

    **API key (header):**

    ```json theme={null}
    {
      "servers": {
        "my-server": {
          "type": "http",
          "url": "https://yoursite.com/mcp/my-server",
          "headers": {
            "X-API-Key": "${input:my-server-key}"
          }
        }
      }
    }
    ```

    **API key (query param) or OAuth:** No `headers` needed — use the plain URL. For query-param keys, append `?keyName=YOUR_KEY` to the URL.

    **File location:** `.vscode/mcp.json` (workspace) · Command Palette → "MCP: Open User Configuration" (global)
  </Step>

  <Step title="Save — VS Code detects the file automatically, no restart needed">
    Save the file. VS Code picks it up automatically without a restart.
  </Step>
</Steps>

<Note>
  No restart needed — VS Code detects the file automatically on save.
</Note>

[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)

***

## OpenAI Playground

<Steps>
  <Step title="Go to platform.openai.com/playground/prompts">
    Go to [platform.openai.com/playground/prompts](https://platform.openai.com/playground/prompts).
  </Step>

  <Step title="Click the tools icon in the left panel, then select Add MCP server">
    Click the **tools icon** in the left panel, then select **Add MCP server**.
  </Step>

  <Step title="Enter the URL and label from the Connection Details below">
    Enter your server URL and a label name.
  </Step>

  <Step title="Under Authentication, select &#x22;Access token / API key&#x22; and paste your API key">
    If your server has authentication enabled (bearer, basic, or API key header), under **Authentication** select **Access token / API key** and paste your token or key value.

    For API key query param or OAuth, leave the authentication field empty — the key is appended to the URL or handled via browser flow.
  </Step>

  <Step title="Copy the URL below, paste it into the URL field, then click Connect">
    Click **Connect**.
  </Step>
</Steps>

<Note>
  No installation needed — OpenAI Playground connects to remote MCP servers natively.
</Note>

[OpenAI Playground MCP docs](https://platform.openai.com/docs/guides/tools-mcp)

***

## Generic MCP Client

Any client that supports the MCP Streamable HTTP transport can connect using:

| Setting          | Value                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **URL**          | `https://yoursite.com/mcp/{slug}`                                                                                          |
| **Transport**    | Streamable HTTP                                                                                                            |
| **Content-Type** | `application/json`                                                                                                         |
| **Auth Header**  | `Authorization: Bearer YOUR_KEY` (bearer) · `Authorization: Basic BASE64` (basic) · `X-API-Key: YOUR_KEY` (api-key header) |

***

## Verifying the Connection

Once connected, ask your AI client to list available tools:

> "What tools do you have available?"

The AI should respond with the tools configured in your GetMCP server.

You can also verify the connection by checking **GetMCP > Analytics** — a successful MCP `initialize` call will appear in the call logs.

<img src="https://mintcdn.com/infiwebs/X3D8lQwdysxDpY3z/images/getmcp-server-connected-mcp-client.png?fit=max&auto=format&n=X3D8lQwdysxDpY3z&q=85&s=5ff4776fdd781240287c0556246afacf" alt="GetMCP Server Connected to AI Client" width="1920" height="1079" data-path="images/getmcp-server-connected-mcp-client.png" />

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused / server not found">
    * Verify HTTPS is properly configured on your WordPress site
    * Check that the server status is **Active** in GetMCP admin
    * Confirm the URL is correct (slug and server\_id match)
    * Ensure the MCP rewrite rules are flushed (visit Settings > Permalinks and click Save)
  </Accordion>

  <Accordion title="403 Forbidden">
    * Your server has inbound authentication enabled
    * Verify the API key or token is correct
    * Ensure the `Authorization` header is being sent correctly for your client
    * For Claude Desktop: auth must be `--header` args in `mcp-remote` (e.g. `"Authorization:Bearer TOKEN"`), not a `headers` JSON key — `mcp-remote` does not support a `headers` object
  </Accordion>

  <Accordion title="503 Service Unavailable">
    * The server is set to **Paused** status
    * Activate the server in GetMCP admin
  </Accordion>

  <Accordion title="Tools not appearing">
    * Ensure tools are set to **Active** status
    * Ask the AI to refresh its tool list
    * In Claude Desktop, fully quit and restart — closing the window is not enough
    * Run `/mcp` in Claude Code to check the server status
  </Accordion>
</AccordionGroup>