Skip to main content
Reason has one MCP server. It gives an MCP client the same operations as the HTTP API.

​
Connect

Then run /mcp in Claude Code, pick reason, and sign in.
Ready-made Claude Code and Codex plugins are at 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 (Settings > API).
  2. Send it as Authorization: Bearer <key> on every request to the MCP URL.

​
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.
  • 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, 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.