openapi: 3.0.3
info:
  title: Jupiter ERP MCP
  version: 1.0.0
  description: >
    MCP endpoint for an agent that already has an API token.

    One HTTP POST carries a JSON-RPC 2.0 message (initialize, tools/list,
    tools/call, ping).

    Amounts inside tool results are integer cents, the same as the Account API.

    The tool catalog is the read tools of the Jupiter AI assistant, limited by
    the token abilities.

    Finalizing, sending, cancelling, paying, and deleting are not tools.
  license:
    name: Protected
servers:
  - url: https://api.jupiter-erp.com/
    description: Production
tags:
  - name: MCP
paths:
  /api/mcp:
    post:
      operationId: handleMcpRequest
      tags:
        - MCP
      summary: Send one MCP JSON-RPC message
      description: >
        A personal access token from Profile, API and MCP requires the
        X-Account-Uuid header.

        Without that header the response is 412.

        A token bound to one account can only be used for that account.

        A token without an account can select any account the user belongs to.

        An OAuth access token is bound to the account chosen at consent.

        For that token the header may be omitted. If it is sent, it must match
        the token account.

        Session tokens from the panel are rejected.

        The account is never taken from a tool argument.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountUuidHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: JSON-RPC result or error for a request that included an id.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "202":
          description: Accepted notification (no id). Empty body.
        "400":
          description: The body is not a JSON-RPC request.
        "401":
          description: Missing or invalid access token.
        "403":
          description: |
            Session token, MCP switched off, token limited to another account,
            user is not a member of the account, or the account is blocked.
        "412":
          description: |
            A personal access token was sent without the X-Account-Uuid header.
            An OAuth access token does not need the header.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    AccountUuidHeader:
      name: X-Account-Uuid
      in: header
      required: false
      description: >
        Required for a personal access token.

        Optional for an OAuth access token, which already carries the account
        from consent.
      schema:
        type: string
        format: uuid
  schemas:
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        id:
          description: String or integer. Omit or null for a notification.
          nullable: true
        method:
          type: string
          enum:
            - initialize
            - ping
            - tools/list
            - tools/call
        params:
          type: object
          additionalProperties: true
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        id:
          description: Echo of the request id.
          nullable: true
        result:
          description: Present on success. Shape depends on the method.
        error:
          $ref: "#/components/schemas/JsonRpcError"
    JsonRpcError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string