Automo MCP API

openapi: 3.2.0
info:
  title: Automo Build MCP API
  version: 1.3.0
  description: 'The machine surface of Automo Build, the AI app builder. All capability calls go through the MCP endpoint (Model Context Protocol, Streamable HTTP): tools are discovered live via tools/list after OAuth sign-in. This document describes that endpoint, the OAuth 2.1 authorization server that protects it, and the discovery documents around them. Start at the server card or the protected-resource metadata; the site overview for agents is https://automo.build/llms.txt; agent registration is walked through at https://automo.build/auth.md.


    Rate limits: the unauthenticated endpoints answer with RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds), counted per client IP. MCP tool calls carry the same headers for the connection''s read, write or spawn budget. Past the limit the answer is 429 with Retry-After.


    Idempotency: POST /agent/identity accepts an Idempotency-Key header (16 to 255 printable characters, a UUID is ideal). A retry with the same key and body answers about the same registration instead of opening a second one; the same key with a different body is refused with 422.


    Versioning and deprecation: the MCP endpoint is versioned by the MCP-Protocol-Version header, whose values are MCP revision dates; every revision listed for it is served from the same URL. info.version follows semantic versioning: additions bump the minor version, breaking changes the major. Before a protocol revision or an operation is removed it is marked deprecated in this document and its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers for at least 90 days.'
  contact:
    name: Automo Build
    url: https://automo.build/contact
    email: support@automo.ai
servers:
- url: https://mcp.automo.build
security:
- oauth2:
  - workspaces:read
  - projects:read
  - projects:write
  - prompts:write
  - sessions:read
  - sessions:write
  - reviews:read
  - reviews:write
  - playbooks:read
  - playbooks:run
  - playbooks:write
  - deployments:read
  - deployments:write
  - chat:read
  - billing:write
tags:
- name: MCP
paths:
  /mcp:
    post:
      operationId: mcp
      summary: The MCP endpoint (Streamable HTTP)
      description: 'Model Context Protocol, revision 2026-07-28 (legacy 2025-11-25 served from the same URL). Every capability of Automo Build is an MCP tool: list them with tools/list after sign-in. Unauthenticated requests answer 401 with a WWW-Authenticate challenge whose resource_metadata URL starts OAuth discovery. Narrower catalog profiles are served at /mcp/core and /mcp/observe.'
      security:
      - oauth2:
        - workspaces:read
        - projects:read
        - projects:write
        - prompts:write
        - sessions:read
        - sessions:write
        - reviews:read
        - reviews:write
        - playbooks:read
        - playbooks:run
        - playbooks:write
        - deployments:read
        - deployments:write
        - chat:read
        - billing:write
      parameters:
      - $ref: '#/components/parameters/McpProtocolVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: A JSON-RPC 2.0 MCP message
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                id:
                  oneOf:
                  - type: string
                  - type: integer
                method:
                  type: string
                  description: e.g. tools/list, tools/call
                params:
                  type: object
                  additionalProperties: true
              required:
              - jsonrpc
              - method
      responses:
        '200':
          description: JSON-RPC response or SSE stream, per the MCP Streamable HTTP transport
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    const: '2.0'
                  id:
                    oneOf:
                    - type: string
                    - type: integer
                  result:
                    type: object
                    additionalProperties: true
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                required:
                - jsonrpc
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Missing or invalid token; WWW-Authenticate carries resource_metadata
        '403':
          description: Token lacks a required scope; WWW-Authenticate names the scopes still needed
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - MCP
components:
  headers:
    RateLimitReset:
      description: Seconds until the window frees a request
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
    RateLimitPolicy:
      description: The limit and its window, as "<limit>;w=<seconds>"
      schema:
        type: string
    RateLimitLimit:
      description: Requests allowed in the current window
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window
      schema:
        type: integer
  schemas:
    OAuthError:
      type: object
      description: RFC 6749 error body
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
      - error
  parameters:
    McpProtocolVersion:
      name: MCP-Protocol-Version
      in: header
      required: false
      description: The MCP revision the client speaks, negotiated at initialize and sent on every later request.
      schema:
        type: string
        enum:
        - '2026-07-28'
        - '2025-11-25'
  responses:
    TooManyRequests:
      description: Rate limited; wait Retry-After seconds
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Automo Build OAuth 2.1: authorization code with PKCE (S256). Clients register by Client ID Metadata Document (the client_id is an HTTPS URL); there is no dynamic client registration. Tokens are JWTs bound to the resource URL, one hour, with rotating refresh tokens.'
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.automo.build/oauth/authorize
          tokenUrl: https://mcp.automo.build/oauth/token
          refreshUrl: https://mcp.automo.build/oauth/token
          scopes:
            workspaces:read: List workspace memberships, whoami, switch the current workspace
            projects:read: List and search projects, project status, env var names, screenshots, deployment history
            projects:write: Create projects, wake sandboxes, share and clone links
            prompts:write: Prompt a project's main agent
            sessions:read: Read any agent session the user can read in the app
            sessions:write: Open, continue and stop agent sessions (CTO, Doctor, Security, QA, Architect, builder spawns)
            reviews:read: 'The sign-off state of builder work: cards, verdicts, fixes, whose move it is'
            reviews:write: Promote, ask a reviewer, hand fixes to the builder, approve or cancel a review
            playbooks:read: List playbooks and read their runs
            playbooks:run: Run a playbook
            playbooks:write: Create and edit playbooks
            deployments:read: Pending publish, deployment status and history
            deployments:write: Propose and approve deployments, publish
            chat:read: Read project chat history
            billing:write: Put a workspace on the Free plan