# Reason plugins for Claude Code, Codex, Cursor and Grok Bot

Connect a coding agent to your Reason workspace at **https://mcp.reasonmachines.com/mcp**.
Sign in through your browser, choose a workspace, review permissions, and connect.
The plugin contains no API key, credential, local executable or hook.

## Install the Reason plugin

### Claude Code

```sh
claude plugin marketplace add reason-machines/reason-plugins
claude plugin install reason@reason
```

Open `/mcp` in Claude Code and authenticate Reason when prompted.

### Codex

```sh
codex plugin marketplace add reason-machines/reason-plugins
codex plugin add reason@reason
```

Enable Reason and complete the browser authentication prompt. Reload the client if
its tool list was already open when you installed the plugin.

These are Reason Machines' publisher-owned plugins. Installation does not depend
on acceptance into Anthropic's curated marketplace or OpenAI's public directory;
those services review and approve listings separately.

### Grok Bot and Cursor

Grok Bot ([x.ai/bot](https://x.ai/bot)) installs plugins from the Cursor
Marketplace, so one Cursor plugin serves both. Once the listing is live, open it
in either app, choose **Add to Grok Bot** or **Add to Cursor**, and complete the
browser sign-in when Reason first asks.

The plugin contains:

- the **reason** skill: how to hand any coding task to Reason, follow it and
  return the session link and pull request;
- slash commands `/reason-fix`, `/reason-build`, `/reason-review`,
  `/reason-fix-ci`, `/reason-ask` and `/reason-status`;
- a **reason-handoff** rule the agent applies when a request touches code;
- the Reason MCP server, `https://mcp.reasonmachines.com/mcp`, with OAuth only.

Until the listing is approved, Cursor can connect the MCP server alone:
[Add Reason to Cursor](https://cursor.com/link/mcp/install?name=reason&config=eyJ1cmwiOiJodHRwczovL21jcC5yZWFzb25tYWNoaW5lcy5jb20vbWNwIn0%3D).

For privacy details, see the [Privacy Policy](https://reasonmachines.com/privacy-policy)
and [Terms of Service](https://reasonmachines.com/terms-of-service). For support,
contact [contact@reasonmachines.com](mailto:contact@reasonmachines.com).

In the Codex app, open **Plugins → Add → Add plugin marketplace**, paste
`https://github.com/reason-machines/reason-plugins`, and add the marketplace. Leave
**Git ref** and **Sparse paths** empty. Select **Reason MCP → Install**, then
complete the browser authentication prompt. No separate MCP configuration is needed.

The marketplace identifier is `reason`.

## Moving from the Ara plugin

Reason was called Ara, and this repository was `Aradotso/ara-mcp`. The `ara`
plugin (and `ara-handoff` before it) connected to a server that is now retired:
`https://api.ara.so/mcp/ara` answers HTTP 410. The `reason` plugin replaces both.

### Claude Code

If you added the marketplace under its old name, it is still registered as `ara`
on your machine. Refresh it and install the plugin under its new name:

```sh
claude plugin marketplace update ara
claude plugin install reason@ara
```

Then open `/mcp` and authenticate Reason. After the refresh Claude Code no longer
loads the retired server and moves your `ara@ara` (or `ara-handoff@ara`) setting
to `reason@ara`; the install fetches the plugin itself.

### Codex

Codex keeps serving an installed plugin until you remove it, so remove the old
one and add the new one:

```sh
codex plugin remove ara@ara
codex plugin marketplace remove ara
codex plugin marketplace add reason-machines/reason-plugins
codex plugin add reason@reason
```

### Cursor and other clients

Delete the `ara` entry whose URL ends in `/mcp/ara` from your MCP configuration
(`~/.cursor/mcp.json` for Cursor) and add the server shown under
[Other MCP clients](#other-mcp-clients).

If you have the Reason CLI, `reason mcp uninstall` removes the retired
registrations from Claude Code, Codex and Cursor in one step.

## More from Reason

- [reason-agent](https://github.com/reason-machines/reason-agent): what Reason Agent is, how to use it, releases and benchmarks.
- [reason-cli](https://github.com/reason-machines/reason-cli): the `reason` command line.
- [reason-marketplace](https://github.com/reason-machines/reason-marketplace): every plugin and connector Reason can use inside your workspace.

## Connect without a plugin

### Claude Code

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

Then open `/mcp` and authenticate Reason.

### Codex

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

### Other MCP clients

Choose a remote **Streamable HTTP** server with URL
`https://mcp.reasonmachines.com/mcp` and OAuth authentication. For example:

```json
{
  "mcpServers": {
    "reason": {
      "type": "http",
      "url": "https://mcp.reasonmachines.com/mcp"
    }
  }
}
```

For headless integrations, a scoped Reason API key can be provided by your
client's secret manager as an Authorization bearer header. Never put a token in
this repository, a prompt, a shared configuration file, or a URL. OAuth credentials
are audience-bound: a REST login cannot be reused as an MCP login.

## Try it

- “Fix the 500 on /api/orders in acme/web and open a PR.” (or `/reason-fix …`)
- “Review https://github.com/acme/web/pull/42.” (or `/reason-review …`)
- “CI is red on my PR #57, make it green without skipping tests.”
- “How does authentication work in acme/api?” (or `/reason-ask …`)
- “Every weekday at 9am, triage new issues in acme/web.”
- “Show my recent Reason sessions.” (or `/reason-status`)

The tools follow the active public v3 contract and your granted scopes. Start with
`getSelf` to check the connected workspace. Path and query arguments are top-level;
JSON request bodies go in `body`. Workspace selection is automatic and pinned to
the connection.

For example, `createSession` accepts
`{"body":{"prompt":"…","repo":"acme/web"}}` and returns the session `url`;
`getSession` accepts `{"sessionId":"…","fields":"status,outcome,result,pr_url"}`.

Creating a session starts asynchronous work; inspect its status before assuming
it finished. Follow pagination cursors for complete lists. Tool results preserve
API status and data, including permission errors, conflicts and rate limits.

All active v3 operations are represented. Deprecated compatibility aliases and
retired routes are omitted. File uploads take `body.filename` and
`body.data_base64`, limited to 1 MiB; use REST for larger uploads. Downloads return
an authorized `download_url`, never forward your Reason bearer to that URL.
Large results are bounded at 2 MiB; request a smaller page or use REST.

## Permissions and disconnection

Each connection is bound to the workspace chosen during consent. Tools reuse the
API's scope, membership, role, private-project and IP access checks. Stored secrets
remain write-only. MCP does not grant arbitrary control of your Mac or bypass a
service's OAuth approval. Revoking a connection or removing its workspace
membership stops access. Use your client's disconnect/logout controls and Reason's
connected-app controls when the integration is no longer needed.

## Publishing to Grok Bot and Cursor

Both listings are reviewed by their marketplaces, and submitting accepts the
[Cursor Marketplace Publisher Terms](https://cursor.com/marketplace-publisher-terms).

1. Merge to `main` and confirm the checks under [Validation](#support-and-validation) pass.
2. **Cursor:** go to [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish)
   and submit `https://github.com/reason-machines/reason-plugins`. Cursor reads
   `.cursor-plugin/marketplace.json` and `plugins/reason/.cursor-plugin/plugin.json`.
3. **Grok Bot:** go to [x.ai/bot/marketplace/submit-a-plugin](https://x.ai/bot/marketplace/submit-a-plugin)
   and select **Grok Bot** and **Cursor** under *Where do you want to be listed?*
   - Organization: Reason Machines; website `https://reasonmachines.com`.
   - Logotype URL: `https://raw.githubusercontent.com/reason-machines/reason-plugins/main/plugins/reason/assets/reason-logo.png`
     (512×512 PNG on an opaque white plate).
   - MCP Server URL or Public GitHub Repository:
     `https://github.com/reason-machines/reason-plugins`.
   - Brief Description: the `description` in `plugins/reason/.cursor-plugin/plugin.json`.
   - Testing Instructions:

     > Install Reason and sign in when prompted (browser OAuth; a Reason account at
     > reasonmachines.com with GitHub connected, no API key). Ask
     > “Show my recent Reason sessions” to confirm the connection. Then run
     > `/reason-ask How is this repository structured? in <owner/repo>` with
     > any repository you connected: the agent returns a reasonmachines.com
     > session link at once and, a few minutes later, an answer that cites
     > files. `/reason-fix <bug> in <owner/repo>` opens a pull request the
     > same way.

## Support and validation

Contact [Reason Machines](mailto:contact@reasonmachines.com).
See [SECURITY.md](SECURITY.md) for vulnerability reporting.

```sh
claude plugin validate --strict plugins/reason
claude plugin validate --strict .claude-plugin/marketplace.json
curl -fsSO https://raw.githubusercontent.com/cursor/plugin-template/main/scripts/validate-template.mjs
node validate-template.mjs   # Cursor's template validator, run from the repository root
```

`tests/test_cursor_plugin.py` checks the Cursor package against the submission
checklist: valid JSON, unique kebab-case names, relative paths that exist, a
square opaque logo, an OAuth-only MCP entry with no undeclared `${VAR}`, and
frontmatter on every skill, command and rule.

`python3 -m unittest discover -s tests` installs the package with the Codex CLI
and checks the manifests, the `renames` map for former plugin names, and
`server.json`, the entry for the [MCP Registry](https://registry.modelcontextprotocol.io).
Publish that entry by running the **Publish to MCP Registry** workflow by hand;
to publish a change, raise `version` in `server.json` first.

Validate the Codex manifest with the Codex plugin validator. Test installations in
an isolated client configuration directory, preserving personal installations.
Production connection and directory approval are separate from manifest validation.