Skip to main content
A plugin connects Reason to another service through an MCP server or a native app connector. Use this page when your own app installs plugins, signs people in to them and removes them, instead of sending people to Customize > Plugins in the Reason app.

What you will have

  • A plugin installed for one person or for the whole team, with its bundled skills.
  • A sign-in your app starts, follows and cancels, which sends the person back to your app.
  • An uninstall that removes the connection and the skills that came with it.

Prerequisites

Create an API key in Settings > API with the scopes below, and export it. Do not paste the key into a file.
For the CLI, you need version 0.2.753 or later. Check with reason --version, and update with curl -fsSL https://reasonmachines.com/install.sh | bash. The CLI signs in with REASON_API_KEY or a saved reason login. See Authentication and scopes.

Base URL and calls

Every call goes to https://api.reasonmachines.com/v3/organizations/{orgId}/plugins, with Authorization: Bearer $REASON_API_KEY. Get orgId once from GET /v3/self (the field is org_id).

What a plugin looks like

listPlugins and getPlugin return the same plugin object. The fields your app needs: Each entry in accounts is one installation: connection_id, adapter (mcp or native), scope (personal, organization or reason), account_id, account_name, connection_state and can_manage. For an MCP installation, connection_id is also its mcp_server_id. A member never sees another member’s personal installation.

Personal or team

scope decides who the installation belongs to. When you send no scope, the install uses the plugin’s scope. The value must be in supported_scopes; anything else is a 400. Bundled skills install in the same scope as the plugin. Team skills belong to owners and admins: a member who installs a plugin for the organization still gets the shared connection, but each team skill reports skill_scope_forbidden in the response. One person can see a personal and a team installation of the same plugin at once. Name the one you mean when you start a sign-in or uninstall.

Install a plugin and its skills

POST /plugins/{slug}/install. Every field is optional. The response has:
  • plugin: the plugin, now with your installation in accounts.
  • mcp_server_id: the installation this call created or found. Null for a native plugin, whose connection is created by its sign-in.
  • already_installed: true when it was already installed in that scope.
  • skills: one entry per bundled skill, with slug, installed, skill_id and error. A skill that fails reports error and does not fail the install.
  • oauth_needed: present for an OAuth or native plugin that still needs a sign-in, with sign_in (the sign-in, when you sent start_sign_in) and error (why it could not start; an MCP plugin stays installed). A native plugin (source: native, such as Slack) has nothing installed until its sign-in succeeds, so when its sign-in cannot start, installPlugin answers with the HTTP error itself and no oauth_needed.
Installing is safe to retry. Installing again in the same scope returns already_installed: true with the same mcp_server_id, and still installs requested skills and starts a requested sign-in. Sending new secrets for an existing installation is a 409 mcp_server_already_installed: change its credentials with Update an MCP server instead. A plugin with connectable: false answers 422 plugin_not_connectable; read its setup.

Sign in from your app

OAuth and native plugins need the person to approve access at the provider. Your app starts the sign-in, opens the provider’s page, and waits for the result.

1. Start it

Either install with start_sign_in: true and read oauth_needed.sign_in, or call POST /plugins/{slug}/sign-in/start for a plugin that is already installed. A catalog plugin that is not installed answers 422 plugin_not_installed. Both return a sign-in: sign_in_id, status (pending), authorize_url, expires_at, plugin_slug, mcp_server_id and return_url. Use a new idempotency_key for each sign-in. A retry with the same key for the same installation returns the same sign-in instead of starting another. A key that already started a sign-in for a different installation is refused with 409 idempotency_key_reused.

2. Open the provider’s page

Open authorize_url in the person’s browser. It is the provider’s consent page. The sign-in expires 15 minutes after it starts (expires_at).

3. Come back to your app

When the sign-in ends, Reason sends the browser to return_url. It accepts:
  • https:// URLs
  • http://localhost and http://127.0.0.1
  • an app scheme, such as myapp://callback
Up to 2,048 characters. Reason rejects with 400: javascript:, data:, vbscript:, file:, blob: and about: URLs, protocol-relative and scheme-less URLs, backslashes, whitespace and control characters, and credentials in the URL. On the redirect Reason adds only sign_in_id, status, connection_id and error, never tokens or codes. Query parameters already in return_url are kept, so you can carry your own state:
Treat the redirect as a hint that the sign-in ended. Anyone can open that URL, so confirm the result with getPluginSignIn before you show the plugin as connected.

4. Read the result

Poll GET /plugins/sign-in/{signInId} until status is no longer pending. The member who started a sign-in can read it, and so can owners and admins.

5. Cancel it

If the person closes your dialog or gives up, send DELETE /plugins/sign-in/{signInId}. Cancelling deletes the one-time OAuth state, so a browser that finishes consent afterwards saves nothing and is sent to return_url with status=cancelled. A browser that finishes after the sign-in expired is sent there with status=expired. For a native connector, a browser that comes back after the sign-in expired, or that was denied at the provider after a cancel, lands on Reason’s own page instead of return_url, so always confirm the outcome with getPluginSignIn. Cancelling is idempotent: a finished, expired or already-cancelled sign-in comes back unchanged. It never removes an existing connection.

Uninstall a plugin

DELETE /plugins/{slug} removes one installation. Name it with a query parameter: With exactly one installation you can manage, you need none of them. With several and none named, the call answers 409 plugin_installation_ambiguous and lists them. You can manage an installation when its can_manage is true: owners and admins can, and so can the member who installed a personal one. Uninstalling revokes the OAuth grant at the provider where the provider supports it. It removes the plugin’s bundled skills in that scope, unless you send keep_skills=true or another installation there still uses them. The response lists removed installations and removed_skills. Uninstalling is safe to retry. Treat 404 plugin_not_installed (plugin_not_found for a custom server) as done: the installation is gone, whether your earlier call or another uninstall removed it. A 502 plugin_uninstall_failed means a native connection could not be removed; try again.

Follow changes

Installs, sign-ins and uninstalls from any surface, the Reason app included, arrive on Stream workspace events as connection.created, connection.updated and connection.removed. On that stream they need mcp:read as well as sessions:read, and a personal connection’s events reach only its owner. Use them to refresh your plugin list instead of polling it.

Worked example with curl

This installs Linear for yourself, signs in, and removes it again. It uses jq.
1. List. Find the plugin, its scopes and its skills.
2. Install for yourself.
3. Start the sign-in with a return link and a new idempotency key.
Open authorize_url in your browser and approve access. 4. Poll until it is no longer pending.
5. Cancel when the person gives up. On a sign-in that already finished, this returns it unchanged.
6. Uninstall your personal installation and its skills.

The same example with the CLI

The CLI finds your organization itself. Path parameters go on the command line; query and body go in JSON through --input-file FILE, or --input-file - for stdin. Each command prints one JSON object with the API response in data.
To install and start the sign-in in one call:
reason tools describe installPlugin prints the exact fields of any operation. Pass --workspace SLUG|ID to use another signed-in Workspace. On an HTTP error the CLI prints an error class and the status, such as {"ok":false,"error":{"code":"conflict","status":409,...}}, not the API’s error code. Call the API directly when your app needs to tell plugin_installation_ambiguous from mcp_server_already_installed.

Errors

Check it works

  • After step 2, GET /plugins/linear lists your installation in accounts with scope: "personal", and each bundled skill shows personal in installed_scopes.
  • After step 4, status is succeeded, and account_name names the account you approved.
  • After step 6, the plugin’s installed is false (unless you also see a team installation), and a second uninstall answers 404 plugin_not_installed.

Next