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

# How to Set Up a Gateway

> Connect a Gateway you've already created to Cursor, Claude, Claude Code, or any other MCP-compatible client.

Once you've [created a Gateway](/mcps/admin-controls/gateway-deployment-creation), the next step is connecting it to the tools you actually work in, like Cursor, Claude Desktop, Claude Code, Windsurf, or any other MCP-compatible client.

<Note>
  This page covers connecting a Gateway you've already created. If you haven't set one up yet, start with [Gateway/Deployment Creation](/mcps/admin-controls/gateway-deployment-creation).
</Note>

## Open Client Setup

<Steps>
  <Step title="Open your Gateway List">
    Navigate to **Secure → Gateway → MCP Gateway**, find the Gateway you want to connect, and click **Client Setup** on its card.
  </Step>

  <Step title="Choose your client">
    Pick the tab for **Cursor**, **Claude Code**, or **Claude**. Each one walks you through the exact steps for that client. If your client isn't one of those three, everything you need is still just the Gateway's URL. See [Connect other clients](#connect-other-clients) below.
  </Step>
</Steps>

<Tip>
  You don't need to open Client Setup just to grab the connection address. **Copy MCP Gateway URL**, available from the card's menu, copies it directly. This is handy if you're following a client's own setup docs and only need the address.
</Tip>

Connecting to a Tenant-level Gateway is still something each person does individually. There's no single login or key shared between coworkers. Everyone who wants to use a Tenant Gateway from their own client opens Client Setup and authenticates with their own account.

## Connect Cursor

<Steps>
  <Step title="Open the Cursor tab">
    Open **Client Setup** on your Gateway and select the **Cursor** tab.
  </Step>

  <Step title="Confirm the install">
    Cursor opens automatically with a prompt to install the connection. Confirm the install.
  </Step>

  <Step title="Sign in">
    Cursor opens your browser to complete sign-in the first time it needs to connect.
  </Step>
</Steps>

<Accordion title="Prefer to add it manually?">
  You can add a Gateway to Cursor by editing `~/.cursor/mcp.json` yourself instead of using the button:

  ```json theme={null}
  {
    "mcpServers": {
      "my-gateway": {
        "url": "https://mcp-gateway.airia.com/gateway/{your-gateway-id}/mcp"
      }
    }
  }
  ```
</Accordion>

## Connect Claude Desktop

The **Claude** tab in Client Setup gives you two ways to connect.

### Remote config (recommended)

<Steps>
  <Step title="Open Custom Connectors">
    In Claude, open your profile menu, then go to **Settings → Feature Preview → Custom Connectors**.
  </Step>

  <Step title="Add the connector">
    Click **Add Connector** and enter a name along with your Gateway's URL, both shown in the Client Setup dialog.
  </Step>

  <Step title="Sign in">
    Claude handles sign-in automatically the first time you use the connector.
  </Step>
</Steps>

### Local config with OAuth

<Steps>
  <Step title="Add the config">
    Copy the configuration shown in Client Setup and add it to your Claude MCP settings file:

    ```json theme={null}
    {
      "mcpServers": {
        "my-gateway": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp-gateway.airia.com/gateway/{your-gateway-id}/mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Fully restart Claude Desktop. It won't pick up the new server until you do.
  </Step>

  <Step title="Sign in">
    Sign in when prompted. OAuth is handled automatically once Claude connects.
  </Step>
</Steps>

<Note>
  Your Claude MCP settings file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart Claude Desktop completely after any change. Closing the window alone isn't enough.
</Note>

## Connect Claude Code

<Steps>
  <Step title="Run the setup command">
    Open **Client Setup** and select the **Claude Code** tab, then run the command it shows you in your terminal:

    ```bash theme={null}
    claude mcp add --scope user --transport http my-gateway "https://mcp-gateway.airia.com/gateway/{your-gateway-id}/mcp"
    ```
  </Step>

  <Step title="Relaunch Claude Code">
    Exit Claude Code completely and relaunch it. The new server won't show up until you do.
  </Step>

  <Step title="Sign in">
    Inside Claude Code, run `/mcp`, select your Gateway, and complete the sign-in flow in your browser.
  </Step>
</Steps>

See Anthropic's [MCP authentication documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#authenticate-with-remote-mcp-servers) for more on how that flow works from Claude Code's side.

## Connect other clients

Cursor, Claude Desktop, and Claude Code get dedicated setup screens because they're the most common clients Airia customers use. A Gateway's endpoint is standards-compliant, so it works with any MCP client that supports remote HTTP servers, including Windsurf, VS Code, and others.

<Steps>
  <Step title="Grab your Gateway's URL">
    Get it from Client Setup, or use **Copy MCP Gateway URL** on the Gateway's card menu.
  </Step>

  <Step title="Add it to your client">
    Add the URL as a remote MCP server, following that client's own instructions for doing so.
  </Step>

  <Step title="Authenticate">
    If your client prompts for authentication, choose OAuth. Your client walks you through a one-time sign-in in your browser and takes care of the rest automatically.
  </Step>
</Steps>

<Note>
  The exact wording and steps for signing in vary a bit from client to client, but every one of them is connecting to the same underlying Gateway the same way.
</Note>

## Gateways with Radar enabled

If a Gateway has [Radar](/mcps/admin-controls/radar) turned on, every step above still applies exactly as written. Client Setup automatically points your client at the right endpoint. If you're adding a client manually and building the URL yourself, use `/radar` instead of `/mcp` at the end.

## About connection names

Airia generates a short name for the Gateway automatically wherever a client needs one to label the connection, based on the Gateway's own name. If that name looks abbreviated or unfamiliar once it shows up in your client, that's expected. You can rename the entry locally in your own configuration. Renaming it on your end never affects the Gateway itself or anyone else connected to it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Gateway connected, but tools don't appear">
    **Cause:** Most MCP clients only load new servers on startup, so closing and reopening a window isn't the same as restarting the app.

    **Fix:** Fully quit and relaunch your client.
  </Accordion>

  <Accordion title="Client isn't prompting for sign-in">
    **Cause:** The sign-in tab opened somewhere you didn't notice.

    **Fix:** Check for a blocked popup or a browser tab that opened in the background.
  </Accordion>

  <Accordion title="A connection that used to work has stopped authenticating">
    **Fix:** Reconnect through Client Setup to re-establish it. See [Credential Recovery](/mcps/end-user-usage/credential-recovery) for the full picture of what can trigger this and how Airia helps you recover.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Gateway/Deployment Creation" icon="plug" href="/mcps/admin-controls/gateway-deployment-creation">
    Create the Gateway you're connecting here
  </Card>

  <Card title="Radar" icon="radar" href="/mcps/admin-controls/radar">
    Keep large Gateways context-efficient
  </Card>

  <Card title="Credential Recovery" icon="arrows-rotate" href="/mcps/end-user-usage/credential-recovery">
    Fix a connection that stops authenticating
  </Card>

  <Card title="Add a Deployment to an Agent" icon="robot" href="/mcps/end-user-usage/how-to-add-a-deployment-to-a-gateway">
    Give an agent tool access instead of an external client
  </Card>
</CardGroup>