Install a plugin

Installs a catalog plugin in scope (personal for the caller’s own account, organization for one shared connection; default the plugin’s scope), or as a Reason’s own connection with reason_id. Owners and admins install any catalog plugin; members install catalog plugins for themselves or the workspace, under the same rules as createMcpServer. Custom servers are added with createMcpServer.

Bundled skills are installed as workspace skills in the same scope unless install_skills is false; skill_slugs picks a subset. Credentials go in secrets (names from secret_names), stored write-only.

An OAuth or native plugin answers with oauth_needed; with start_sign_in it also starts the browser sign-in and returns it (the provider’s authorize_url, sign_in_id, expires_at). Installing what is already installed in that scope is not an error: it returns already_installed and still installs the requested skills and starts a requested sign-in.

_{Scope: mcp:write}

POST /v3/organizations/{orgId}/plugins/{slug}/install

Install a plugin

cURL

curl --request POST \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/plugins/{slug}/install \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "secrets": {},
  "install_skills": true,
  "skill_slugs": [
    "<string>"
  ],
  "start_sign_in": true,
  "return_url": "<string>",
  "idempotency_key": "<string>"
}
'

200

{
  "plugin": {
    "slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "icon": "<string>",
    "source": "curated",
    "auth_type": "none",
    "secret_names": [
      "<string>"
    ],
    "scope": "personal",
    "supported_scopes": [
      "personal"
    ],
    "connectable": true,
    "setup": {
      "code": "<string>",
      "owner": "<string>",
      "message": "<string>"
    },
    "docs_url": "<string>",
    "website_url": "<string>",
    "verified": true,
    "bundled_skills": [
      {
        "slug": "<string>",
        "name": "<string>",
        "description": "<string>",
        "installed": true,
        "installed_scopes": [
          "personal"
        ]
      }
    ],
    "installed": true,
    "mcp_server_id": "<string>",
    "connection_state": "<string>",
    "connection_checked_at": "<string>",
    "accounts": [
      {
        "connection_id": "<string>",
        "adapter": "mcp",
        "mcp_server_id": "<string>",
        "scope": "personal",
        "reason_id": "<string>",
        "account_id": "<string>",
        "account_name": "<string>",
        "connection_state": "<string>",
        "connection_checked_at": "<string>",
        "connection_error_code": "<string>",
        "enabled": true,
        "can_manage": true,
        "reason_mode": "member"
      }
    ]
  },
  "mcp_server_id": "<string>",
  "already_installed": true,
  "skills": [
    {
      "slug": "<string>",
      "installed": true,
      "skill_id": "<string>",
      "error": "<string>"
    }
  ],
  "oauth_needed": {
    "sign_in": {
      "sign_in_id": "<string>",
      "status": "pending",
      "authorize_url": "<string>",
      "expires_at": "<string>",
      "adapter": "mcp",
      "plugin_slug": "<string>",
      "mcp_server_id": "<string>",
      "connection_id": "<string>",
      "account_id": "<string>",
      "account_name": "<string>",
      "error_code": "<string>",
      "error_message": "<string>",
      "return_url": "<string>",
      "completed_at": "<string>",
      "created_at": "<string>"
    },
    "error": {
      "code": "<string>",
      "message": "<string>",
      "redirect_uri": "<string>"
    }
  }
}

Authorizations

Authorization · string · header · required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Scopes

mcp:write

Path Parameters

orgId · string · required

Organization id or slug. Resolve it with GET /v3/self.

slug · string · required

Plugin slug from listPlugins, stable across installs and uninstalls.

Required string length: 1 - 120

Body

application/json

scope · enum<string>

personal installs it for the caller's own account; organization installs one shared connection for the workspace. Defaults to the plugin's scope; must be one of its supported_scopes. Ignored with reason_id.

Available options: personal, organization

reason_id · string<uuid>

Install it as this Reason's own connection (requires managing the Reason).

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

secrets · object

Credentials keyed by a name from secret_names (for example MCP_API_KEY). Write-only: stored encrypted, never returned.

Show child attributes

install_skills · boolean

Install the plugin's bundled skills as workspace skills in the same scope. Default true.

skill_slugs · string[]

Install only these bundled_skills slugs. Omit to install all; an unknown slug is a 400 naming the valid ones.

Maximum array length: 100

Required string length: 1 - 200

start_sign_in · boolean

For an OAuth or native plugin: start the browser sign-in now and return it in oauth_needed.sign_in (with its authorize_url). Default false: call startPluginSignIn later.

return_url · string

Where the OAuth callback sends the browser when sign-in ends: https://, http://localhost or http://127.0.0.1, or an app scheme such as myapp://callback. javascript:, data:, vbscript:, file:, blob:, about:, protocol-relative URLs, backslashes, control characters and credentials are rejected. Reason sets only sign_in_id, status, connection_id and error on the redirect, never tokens or codes; parameters already in return_url are kept as they were.

Maximum string length: 2048

idempotency_key · string

With start_sign_in: reuses the sign-in you started with this key.

Required string length: 1 - 200

Response

200

application/json

Installed, or already installed in that scope.

plugin · object · required

Show child attributes

mcp_server_id · string | null · required

The installation this call created or found (MCP); null for a native plugin, whose connection is created by its sign-in.

already_installed · boolean · required

True when it was already installed in this scope; the call still installs requested skills and starts a requested sign-in.

skills · object[] · required

Result for each bundled skill this call installed; empty with install_skills false. A skill whose package cannot be resolved reports error and does not fail the install.

Show child attributes

oauth_needed · object

Present when the installation still needs a browser sign-in.

Show child attributes