> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect over MCP

> Connect Claude Code, Codex, or any MCP client to Reason.

Reason has one MCP server. It gives an MCP client the same operations as the [HTTP API](/api-reference/account/verify-credentials).

| | |
| - | - |
| URL | `https://mcp.reasonmachines.com/mcp` |
| Transport | Streamable HTTP |
| Sign-in | OAuth with dynamic client registration, or a Reason API key |

## Connect

<Tabs>
  <Tab title="Claude Code">
    ```bash wrap theme={null}
    claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp
    ```

    Then run `/mcp` in Claude Code, pick `reason`, and sign in.
  </Tab>

  <Tab title="Codex">
    ```bash wrap theme={null}
    codex mcp add reason --url https://mcp.reasonmachines.com/mcp
    codex mcp login reason
    ```
  </Tab>

  <Tab title="Any MCP client">
    Add a remote (HTTP) MCP server with the URL `https://mcp.reasonmachines.com/mcp`. Leave the client ID and secret empty. The client registers itself, opens your browser, and you sign in to Reason and choose a workspace.
  </Tab>
</Tabs>

Ready-made Claude Code and Codex plugins are at [reason-machines/reason-plugins](https://github.com/reason-machines/reason-plugins).

## Sign in with OAuth

Any client that follows the MCP authorization spec works without setup. This is what it does:

1. It sends a request to `https://mcp.reasonmachines.com/mcp` with no token. The reply is `401` with a `WWW-Authenticate` header that names the resource metadata.
2. It reads `https://mcp.reasonmachines.com/.well-known/oauth-protected-resource/mcp` to find the authorization server.
3. It reads `/.well-known/oauth-authorization-server` on that server and registers itself at the `registration_endpoint`. Clients are public: no client secret.
4. It runs the authorization code flow with PKCE (`S256`) and `resource=https://mcp.reasonmachines.com/mcp`. You sign in and choose one workspace.
5. It sends the access token as `Authorization: Bearer <token>`. Access tokens last one hour. The client renews them with its refresh token.

A token issued for the HTTP API does not work at the MCP URL, and the reverse. Each connection is tied to the one workspace you chose.

## Sign in with an API key

Use a key when no browser is available, such as in CI.

1. Create a key at [reasonmachines.com/customize?tab=api](https://reasonmachines.com/customize?tab=api) (Settings > API).
2. Send it as `Authorization: Bearer <key>` on every request to the MCP URL.

```bash wrap theme={null}
claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp --header "Authorization: Bearer $REASON_API_KEY"
```

```bash wrap theme={null}
codex mcp add reason --url https://mcp.reasonmachines.com/mcp --bearer-token-env-var REASON_API_KEY
```

## Scopes

A connection can do only what its scopes allow. Scopes are the same for OAuth and API keys, for example `run`, `sessions:read`, `repos:read`, and `org:read`.

* OAuth: the sign-in screen shows what the client asked for. A client that asks for nothing gets every scope except `ssh:write`.
* API key: you choose the scopes when you create the key.
* The full list is `scopes_supported` in the [resource metadata](https://mcp.reasonmachines.com/.well-known/oauth-protected-resource/mcp).
* Call `getSelf` to see the scopes your connection holds.

## Tools

Each tool is one HTTP API operation. The tool name is the operation ID in the [API reference](/api-reference/account/verify-credentials), such as `getSelf`, `listProjects`, `listSessions`, `createSession`, `getSession`, `listSessionMessages`, and `sendSessionMessage`.

* You see only the tools your scopes allow.
* The workspace is set by your connection. Tools take no `orgId`.
* Path and query values are top-level arguments. A request body goes in `body`.
* `tools/list` returns 30 tools per page. Follow `nextCursor`.
* Start with `getSelf`, `listProjects`, or `listSessions`.
* `createSession` starts work that runs after the call returns. Poll `getSession` until `status` is no longer `running`, then check `outcome`.
* Results are capped at 2 MiB. Ask for a smaller page if you hit the cap.
* File uploads are base64 and capped at 1 MiB. Use the HTTP API for larger files.

## If it does not connect

* `401` with `missing_bearer`: this is the normal first reply. Your client has not signed in yet. Run its sign-in step.
* `405` on `GET`: the server answers `POST` only. It has no event stream.
* `410` with `mcp_transport_retired`: you are using the old `/mcp/ara` address. Use the URL above.
* The server is not at `reasonmachines.com/mcp` or `api.reasonmachines.com/v3/mcp`. Use `https://mcp.reasonmachines.com/mcp`.

Agents can read the same guidance as plain text at [reasonmachines.com/llms.txt](https://reasonmachines.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.