Reason MCP Server

What is Reason MCP Server?

The Reason MCP server is Reason's official hosted endpoint that lets Claude Code, Codex or any MCP client drive Reason, an autonomous AI software engineer: start coding sessions, message your Reasons and track the pull requests they open.

Reason, from Reason Machines, is a cloud coding agent for GitHub. You connect a repository, assign issues, and Reason's agents open evidence-backed pull requests with screen recordings, logs and review-ready diffs. Reason has one MCP server, and it gives an MCP client the same operations as Reason's HTTP API: every tool maps to one API operation, limited by your connection's scopes and tied to one workspace.

How to use Reason MCP Server?

The server uses the Streamable HTTP transport at:

https://mcp.reasonmachines.com/mcp

You need a Reason account. There are two ways to sign in:

• OAuth (recommended for interactive use): the client registers itself through dynamic client registration, so no client ID or secret is needed. It opens your browser, you sign in to Reason and choose one workspace, and the client renews its one-hour access tokens with a refresh token. An unauthenticated request returns 401 with a WWW-Authenticate header; that is the start of sign-in, not a failure.
• API key (for CI or anywhere without a browser): create a key in Reason under Settings > API (reasonmachines.com/customize?tab=api) and send it as Authorization: Bearer <key>.

Claude Code

claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp

Then run /mcp in Claude Code, pick reason and sign in. Without a browser, pass your key instead:

claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp --header "Authorization: Bearer $REASON_API_KEY"

Codex

Reason documents this setup:

codex mcp add reason --url https://mcp.reasonmachines.com/mcp
codex mcp login reason

Claude Desktop / claude.ai

Add a custom connector with the URL https://mcp.reasonmachines.com/mcp. Leave the client ID and secret empty; the client registers itself and opens your browser to sign in.

Cursor

In ~/.cursor/mcp.json or a project's .cursor/mcp.json:

{
  "mcpServers": {
    "reason": {
      "url": "https://mcp.reasonmachines.com/mcp"
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "reason": {
      "type": "http",
      "url": "https://mcp.reasonmachines.com/mcp"
    }
  }
}

Reason also publishes ready-made Claude Code and Codex plugins in the reason-machines/reason-plugins GitHub repository.

Key features of Reason MCP Server

• Official server run by Reason Machines, with the same operations as the Reason HTTP API.
• OAuth with dynamic client registration and PKCE, or a Reason API key for headless use.
• Scope-based access: a connection sees only the tools its scopes allow, for example run, sessions:read, repos:read and org:read. An OAuth client that asks for no specific scopes gets every scope except ssh:write.
• One workspace per connection, so tools take no organization ID.
• Start sessions that keep running after the call returns, then poll them for status and outcome.
• Message named Reasons and read their replies, and create, update or archive Reasons.
• Separate token audiences: a token issued for the HTTP API does not work at the MCP URL, and the reverse.

Use cases of Reason MCP Server

• Handing off a task from your editor: "Start a Reason session to fix the flaky auth test, add a regression case and open a PR."
• Checking on running work: "List my recent Reason sessions and tell me which ones are still running."
• Following up on a result: "Get the outcome of the last session and give me the pull request link."
• Talking to a named Reason: "Ask our backend Reason why the nightly export is slow and read me its reply."
• Running Reason from CI: connect with an API key and a narrowly scoped connection so a pipeline can create sessions without a browser.

Reason's docs suggest starting with getSelf (which also shows the scopes your connection holds) or listSessions. createSession starts work in the background: poll getSession until status is no longer running, then check outcome. To message a Reason, find it with listReasons, get its conversation's session_id from openReasonConversation, send with sendSessionMessage and read the reply with listSessionConversation.

Troubleshooting Reason MCP Server

• 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 and has no event stream.
• 410 with mcp_transport_retired: you are using the old /mcp/ara address. Use https://mcp.reasonmachines.com/mcp.
• A tool is missing: you see only the tools your scopes allow, and tools/list returns 30 tools per page, so follow nextCursor.