9bot MCP API

openapi: 3.2.0
info:
  title: 9bot Agent and Gateway MCP API
  summary: Public discovery and transport surface for the 9bot AI agent gateway.
  description: This OpenAPI description documents the public 9bot MCP gateway surface, OAuth and MCP discovery resources, health information, and generic JSON-RPC envelopes. Exact 9bot tool names and input schemas are discovered dynamically after OAuth authorization and depend on application scopes, authorized groups, tool policies, tenant configuration, and feature availability.
  version: 1.0.0
  contact:
    name: 9bot
    url: https://9bot.com.br/developers/
    email: contato@9bot.com.br
servers:
- url: https://mcp.9bot.com.br
  description: Production 9bot MCP and OAuth gateway
tags:
- name: MCP
  description: OAuth-protected Model Context Protocol transport.
paths:
  /mcp:
    post:
      tags:
      - MCP
      operationId: exchangeMcpMessage
      summary: Exchange an MCP message
      description: Sends a JSON-RPC 2.0 MCP request or notification to the remote 9bot gateway. Compatible clients should use a current MCP SDK, negotiate the protocol version, and discover available tools after authorization. The gateway may return a JSON response or a request-scoped Server-Sent Events stream. The exact tool catalog is not enumerated in this OpenAPI file.
      security:
      - OAuthBearer: []
      parameters:
      - name: Accept
        in: header
        required: false
        description: MCP clients normally accept JSON and may accept Server-Sent Events.
        schema:
          type: string
          default: application/json, text/event-stream
      - name: MCP-Protocol-Version
        in: header
        required: false
        description: Protocol version negotiated by the MCP client and server when required.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcClientPayload'
            examples:
              listTools:
                summary: Discover tools available to the authorized application
                value:
                  jsonrpc: '2.0'
                  id: tools-1
                  method: tools/list
                  params: {}
              callDiscoveredTool:
                summary: Call a tool returned by tools/list
                value:
                  jsonrpc: '2.0'
                  id: call-1
                  method: tools/call
                  params:
                    name: <tool-name-from-tools-list>
                    arguments: {}
      responses:
        '200':
          description: JSON-RPC response or a request-scoped event stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcServerPayload'
            text/event-stream:
              schema:
                type: string
                description: A Server-Sent Events stream containing MCP JSON-RPC messages.
        '202':
          description: Notification accepted without a JSON-RPC response body.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    BadRequest:
      description: Invalid request, media type, protocol envelope, or parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    RateLimited:
      description: The request exceeded a gateway, tenant, token, tool, or IP rate limit.
      headers:
        Retry-After:
          description: When present, the delay before a retry.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Unauthorized:
      description: OAuth authorization is missing, expired, invalid, or not accepted.
      headers:
        WWW-Authenticate:
          description: Bearer challenge and protected resource metadata hint when available.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    ServerError:
      description: Temporary gateway or dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Forbidden:
      description: The application lacks the required scope, group access, tool permission, or tenant policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
  schemas:
    JsonRpcError:
      type: object
      additionalProperties: false
      required:
      - code
      - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          description: Optional structured error information.
    JsonRpcClientPayload:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcClientMessage'
      - type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/JsonRpcClientMessage'
    JsonRpcSuccessResponse:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - result
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        result:
          description: Method-specific result.
    JsonRpcRequest:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        method:
          type: string
          minLength: 1
        params:
          oneOf:
          - type: object
          - type: array
          description: Method-specific parameters.
    JsonRpcClientMessage:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcRequest'
      - $ref: '#/components/schemas/JsonRpcNotification'
    JsonRpcId:
      oneOf:
      - type: string
      - type: integer
      description: A client-selected JSON-RPC request identifier.
    HttpError:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        error_description:
          type: string
        message:
          type: string
        request_id:
          type: string
    JsonRpcNotification:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        method:
          type: string
          minLength: 1
        params:
          oneOf:
          - type: object
          - type: array
          description: Method-specific parameters.
    JsonRpcErrorResponse:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - error
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - $ref: '#/components/schemas/JsonRpcId'
          - type: 'null'
        error:
          $ref: '#/components/schemas/JsonRpcError'
    JsonRpcServerPayload:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcServerMessage'
      - type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/JsonRpcServerMessage'
    JsonRpcServerMessage:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcSuccessResponse'
      - $ref: '#/components/schemas/JsonRpcErrorResponse'
      - $ref: '#/components/schemas/JsonRpcNotification'
      - $ref: '#/components/schemas/JsonRpcRequest'
  securitySchemes:
    OAuthBearer:
      type: http
      scheme: bearer
      bearerFormat: OAuth 2.1 access token
      description: Obtain authorization using the protected resource and authorization server metadata. Exact scopes and endpoints are advertised by the production metadata.
externalDocs:
  description: 9bot developer documentation
  url: https://9bot.com.br/developers/
x-service-info:
  categories:
  - messaging
  - automation
  - ai
  - productivity
  docs:
    homepage: https://9bot.com.br/
    apiReference: https://9bot.com.br/developers/
    llms: https://9bot.com.br/llms.txt
x-9bot-ai-interfaces:
  mcp: https://mcp.9bot.com.br/mcp
  webmcp: https://9bot.com.br/developers/webmcp/
  llms: https://9bot.com.br/llms.txt
  llmsFull: https://9bot.com.br/llms-full.txt
x-9bot-commerce:
  plan: 9bot Basic Pro (monthly subscription)
  free_trial_days: 7
  offers:
  - language: pt
    currency: BRL
    intro_amount: '175.00'
    intro_months: 3
    regular_amount: '350.00'
    checkout_url: https://9bot.com.br/pt/comecar-agora/
    onboarding_url: https://9bot.com.br/pt/onboarding/
  - language: en
    currency: USD
    intro_amount: '35.00'
    intro_months: 3
    regular_amount: '70.00'
    checkout_url: https://9bot.com.br/en/start-now/
    onboarding_url: https://9bot.com.br/en/onboarding/
  - language: es
    currency: USD
    intro_amount: '35.00'
    intro_months: 3
    regular_amount: '70.00'
    checkout_url: https://9bot.com.br/es/planes/
    onboarding_url: https://9bot.com.br/es/onboarding/
  - language: zh
    currency: CNY
    intro_amount: '230.00'
    intro_months: 3
    regular_amount: '460.00'
    checkout_url: https://9bot.com.br/zh/start-now/
    onboarding_url: https://9bot.com.br/zh/onboarding/
  purchase_flow: 'Human-in-the-loop: open the checkout page, connect WhatsApp by scanning a QR code (or pairing code), pay on the hosted checkout; the 9bot Dashboard is deployed within about 5 minutes.'
  machine_payment_endpoints: none yet (no operation in this document accepts payment)