> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# Connect an MCP client

The Gateway is an MCP server over Streamable HTTP.

|                       |                                                        |
| --------------------- | ------------------------------------------------------ |
| **Address**           | `https://mcp.basement.chat/mcp`                        |
| **Transport**         | Streamable HTTP (JSON-RPC over `POST`)                 |
| **Protocol versions** | `2025-06-18`, `2025-03-26`, `2024-11-05`               |
| **Sign in**           | A key (`Authorization: Bearer bsmt_...`), or OAuth 2.1 |

## Sign in with a key

Create a key in **Agents**, **Connect agent**, and send it as a bearer token. This works with every MCP client that can set a header.

#### JSON settings

Most clients (Claude Desktop, Cursor, Windsurf and others) read a file like this one:

```json
{
  "mcpServers": {
    "basement": {
      "url": "https://mcp.basement.chat/mcp",
      "headers": { "Authorization": "Bearer bsmt_your_key" }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add --transport http basement https://mcp.basement.chat/mcp \
  --header "Authorization: Bearer bsmt_your_key"
```

#### Codex

In `~/.codex/config.toml`:

```toml
[mcp_servers.basement]
url = "https://mcp.basement.chat/mcp"
bearer_token_env_var = "BASEMENT_API_KEY"
```

Then set `BASEMENT_API_KEY` to the key in your environment.

## Sign in with OAuth

A client that supports OAuth for MCP (for example a custom connector in Claude) needs only the address. Give it `https://mcp.basement.chat/mcp`. The client opens Basement in the browser, you choose the organization and give the connection a name, and Basement gives the client a key of its own.

A connection made this way reads Basement and writes nothing. To let it do more, select an access level for it in **Agents**, **Connected**.

The Gateway implements OAuth 2.1 with discovery, dynamic client registration and PKCE:

* `GET /.well-known/oauth-protected-resource`
* `GET /.well-known/oauth-authorization-server`
* `POST /oauth/register`
* `POST /oauth/token`

A connection made with OAuth shows in **Agents**, **Connected** like any other key, and you revoke it the same way.

## Check the connection

Call `whoami`. It answers the organization, the key's name and prefix, and the key's scopes. It works for every key.

```json
{
  "orgId": "…",
  "orgName": "Acme Robotics",
  "keyName": "Claude for call prep",
  "keyPrefix": "bsmt_4UMl",
  "scopes": ["gateway:read", "tools:use"],
  "expiresAt": null
}
```

## What the agent sees

`tools/list` answers only the tools that the key's access level allows. A tool that is not in the list answers an error if the agent calls it. See [Tools](/mcp/tools).