Elaichi MCP control plane API

openapi: 3.2.0
info:
  title: Elaichi MCP control plane API
  version: 0.1.0
  description: 'Control-plane HTTP API for Elaichi, the MCP control plane for SaaS teams. Authenticate with an organization API token (create one in the Elaichi app under Settings → API tokens) sent as a bearer token, plus the `X-Organization-Id` header on org-scoped routes; the MCP and OAuth endpoints use their own protocols. A few actions are deliberately not available to an API token and must be done by a person in the Elaichi app: managing API and SCIM tokens, creating an organization, approving an access request, deleting an organization, and changing the two-factor requirement. The operations concerned say so. Endpoints used only by the Elaichi app itself (sign-in, consent screens, browser redirects, inbound webhooks) are not documented.'
servers:
- url: https://api.elaichi.ai
  description: Production
tags:
- name: MCP control plane
paths:
  /mcp:
    post:
      operationId: mcpControlPlaneJsonRpc
      summary: Send a JSON-RPC request to the MCP server
      tags:
      - MCP control plane
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    enum:
                    - '2.0'
                  id: {}
                  result: {}
                  error:
                    type: object
                    description: JSON-RPC error object. Transport-level failures use HTTP status codes instead.
                    additionalProperties: true
        '202':
          description: Accepted — a JSON-RPC notification (no `id`) produces no response body.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, expired or revoked access token. Carries `WWW-Authenticate` with `resource_metadata`; `error="invalid_token"` is present only when a credential was actually supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            WWW-Authenticate:
              description: RFC 9728 §5.1 challenge pointing at the protected-resource metadata document.
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Handles JSON-RPC requests from an MCP client. The endpoint an MCP client (Claude Desktop, a claude.ai connector, Cursor) connects to after the user signs in to Elaichi. JSON-RPC 2.0 over the MCP Streamable HTTP transport, stateless, and it exposes the whole organization for one user: the control-plane operation catalog (members, teams, roles, connections, templates, toolboxes…) as `elaichi__*` tools and — when the grant carries `mcp:tools` — the user''s own connected third-party tools (under "All my tools", every tool of every connection they can use, resolved through their virtual `global:{user_id}` toolbox, plus every toolbox shared with them at `use` or above) under their own `{account}__{tool}` names.


        **Authentication.** `Authorization: Bearer ` from `POST /oauth/token`. Session cookies and org API tokens are not accepted here. The organization is pinned on the grant at consent time, so `X-Organization-Id` is neither sent nor honored.


        **Discovery.** A 401 carries a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at `/.well-known/oauth-protected-resource`. That header is how a client that holds no credential finds the authorization server and starts the OAuth flow — a bare 401 is a dead end. A valid token that simply lacks a scope gets `error="insufficient_scope"` with the required `scope`, meaning re-authorize for more rather than re-authenticate.


        **Authorization.** Two independent gates, both of which must pass: the grant''s scopes (what the user let this client do) and the user''s RBAC permissions, re-read per request so a revoked role takes effect before the token expires. `tools/list` advertises only what the scopes cover, and `tools/call` re-checks them. Revoking the grant kills the token on its very next request. Refused (403 subscription_required) while the organization''s plan is on hold; a non-member gets 403, not 401. On the Personal plan only the organization''s primary owner may use it: anyone else gets 403 `plan_single_user`, or, for `tools/call`, an error result with the same sentence. Rate limited per token.'
      security:
      - mcpOAuth:
        - mcp:read
        - mcp:write
        - mcp:destructive
        - mcp:tools
        - openid
        - email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                id:
                  description: String or number. Omitted for notifications, which answer 202 with no body.
                method:
                  type: string
                  description: 'MCP method: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `ping`, and the empty `resources/list` / `prompts/list`.'
                params:
                  type: object
                  additionalProperties: true
    get:
      operationId: mcpControlPlaneGetNotAllowed
      summary: Reject this method on the MCP endpoint
      tags:
      - MCP control plane
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: 'Method Not Allowed, with `Allow: POST`. This transport is POST-only: there is no server-initiated SSE stream to open with GET, and no session to tear down with DELETE.'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Answers `405` with `Allow: POST`. The MCP endpoint is POST-only: there is no server-sent event stream to open with GET.'
      security: []
    delete:
      operationId: mcpControlPlaneDeleteNotAllowed
      summary: Reject this method on the MCP endpoint
      tags:
      - MCP control plane
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: 'Method Not Allowed, with `Allow: POST`. This transport is POST-only: there is no server-initiated SSE stream to open with GET, and no session to tear down with DELETE.'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Answers `405` with `Allow: POST`. The MCP endpoint is POST-only: there is no session to end with DELETE.'
      security: []
components:
  schemas:
    Error:
      type: object
      required:
      - error
      description: The Elaichi error envelope. The MCP OAuth endpoints under `/oauth` are the exception — they return RFC 6749 errors instead (see `OAuthError`).
      properties:
        error:
          type: object
          required:
          - message
          - code
          properties:
            message:
              type: string
              description: Human-readable. 5xx messages are deliberately generic.
            code:
              type: string
              description: Stable machine-readable code, e.g. `not_found`, `subscription_required`.
            details:
              description: Structured detail for codes that carry one, e.g. `toolboxes_need_resolution`.
            feature:
              type: string
              description: The gated feature, on entitlement failures.
            plan:
              type:
              - string
              - 'null'
              enum:
              - personal
              - gold
              - black
              - null
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session or API token
      description: '`Authorization: Bearer <token>` with an org-scoped API token (`elch_{org_id}_{64 hex}`), created in the Elaichi app under Settings → API tokens. The Elaichi app itself signs in with a session cookie, which is also accepted but is not meant for integrations. Two other credential families exist and are NOT interchangeable with this one: an MCP OAuth access token (`POST /mcp` only) and a SCIM token (`/scim/v2/*` only).'
    mcpOAuth:
      type: oauth2
      description: MCP OAuth access token, used only by `POST /mcp` — not interchangeable with `bearerAuth`. Discovered per RFC 9728/8414 at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`.
      flows:
        authorizationCode:
          authorizationUrl: https://api.elaichi.ai/oauth/authorize
          tokenUrl: https://api.elaichi.ai/oauth/token
          scopes:
            mcp:read: Anything you can already see in Elaichi. Never secret values. It can also ask an admin for access to something restricted for you.
            mcp:write: Create and change teams, roles, toolboxes, templates and connections, and share access.
            mcp:destructive: Permanently delete data and remove access in Elaichi. This cannot be undone.
            mcp:tools: Run tools from the toolboxes you choose next, deleting in your connected apps included. It can also ask an admin for access to something restricted for you.
            openid: That you are signed in, and the user ID we use for you. Nothing else.
            email: Your email address, and whether it is verified. Apps use this to check your domain.