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

# Connect a client

> Set up Claude Code, Codex, Cursor, OpenCode, and more to use the Mesa MCP server.

Every client connects to the same endpoint over Streamable HTTP:

```
https://api.mesa.dev/mcp
```

You authenticate in one of two ways:

* **OAuth (recommended).** Sign in from inside your client; a browser window handles consent. There is no key to copy, and the client refreshes the session for you.
* **API key.** Pass a Mesa API key as an `Authorization: Bearer` header. Use a [repo-scoped key](/content/reference/mcp/authentication#scopes-and-repository-access) when you want to limit the agent to specific repositories.

Both resolve to the same access. Pick the client below.

## Claude Code

Add the server with the CLI, then authenticate:

```bash theme={null}
claude mcp add --transport http mesa https://api.mesa.dev/mcp
```

Start Claude Code, run `/mcp`, select **mesa**, and choose **Authenticate**. A browser window opens for OAuth sign-in.

<Accordion title="Use an API key instead of OAuth">
  Pass the key as a header when you add the server:

  ```bash theme={null}
  claude mcp add --transport http mesa https://api.mesa.dev/mcp \
    --header "Authorization: Bearer ${MESA_API_KEY}"
  ```

  With a header set, the connection is authenticated immediately.
</Accordion>

## Codex

Add the server to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.mesa]
url = "https://api.mesa.dev/mcp"
```

Codex speaks Streamable HTTP natively. Trigger OAuth sign-in with:

```bash theme={null}
codex mcp login mesa
```

<Accordion title="Use an API key instead of OAuth">
  Point Codex at an environment variable holding your key:

  ```toml theme={null}
  [mcp_servers.mesa]
  url = "https://api.mesa.dev/mcp"
  bearer_token_env_var = "MESA_API_KEY"
  ```
</Accordion>

## Cursor

Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` to make it global):

```json theme={null}
{
  "mcpServers": {
    "mesa": {
      "url": "https://api.mesa.dev/mcp"
    }
  }
}
```

Open **Settings → MCP**, find **mesa**, and click **Connect** to run the OAuth sign-in. Cursor handles the OAuth discovery and consent flow automatically.

## OpenCode

Add the server to `opencode.json` (project root) or `~/.config/opencode/opencode.json`:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mesa": {
      "type": "remote",
      "url": "https://api.mesa.dev/mcp",
      "enabled": true
    }
  }
}
```

OpenCode runs the OAuth flow automatically on first use and caches the session.

<Accordion title="Use an API key instead of OAuth">
  Disable OAuth for the server and pass the key as a header (note OpenCode's `{env:VAR}` interpolation — no `$`):

  ```json theme={null}
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "mesa": {
        "type": "remote",
        "url": "https://api.mesa.dev/mcp",
        "enabled": true,
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:MESA_API_KEY}"
        }
      }
    }
  }
  ```
</Accordion>

## Claude Desktop & Cowork

Open **Settings → Connectors → Add custom connector**, name it `mesa`, and enter the URL:

```
https://api.mesa.dev/mcp
```

Claude completes OAuth sign-in when you add the connector.

## Clients without native remote support

If your client only speaks stdio, bridge to the remote server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json theme={null}
{
  "mcpServers": {
    "mesa": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.mesa.dev/mcp", "--transport", "http"]
    }
  }
}
```

`mcp-remote` runs the OAuth flow and caches the token, so the bridged client gets the same sign-in experience.