Dust MCP API

openapi: 3.2.0
info:
  title: DUST API Documentation MCP API
  version: 1.0.2
  description: The OpenAPI specification for the Dust.tt API
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://dust.tt
  description: Dust.tt API (us-central1)
- url: https://eu.dust.tt
  description: Dust.tt API (europe-west1)
tags:
- name: MCP
  description: MCP servers
paths:
  /api/v1/w/{wId}/mcp/deregister:
    post:
      summary: Deregister a client-side MCP server
      description: 'Documentation

        Remove a previously registered client-side MCP server registration.'
      tags:
      - MCP
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serverId
              properties:
                serverId:
                  type: string
                  description: The ID of the registered MCP server
      responses:
        '200':
          description: Server deregistered successfully
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. User does not have access to the workspace.
      operationId: postApiV1WByWIdMcpDeregister
      x-operation-id-source: derived
  /api/v1/w/{wId}/mcp/heartbeat:
    post:
      summary: Update heartbeat for a client-side MCP server
      description: 'Documentation

        Update the heartbeat for a previously registered client-side MCP server.

        This extends the TTL for the server registration.'
      tags:
      - MCP
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serverId
              properties:
                serverId:
                  type: string
                  description: The ID of the registered MCP server
      responses:
        '200':
          description: Heartbeat updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  expiresAt:
                    type: string
                    format: date-time
        '400':
          description: Bad Request. Missing or invalid parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. User does not have access to the workspace.
        '404':
          description: Not Found. MCP server not registered or expired.
      operationId: postApiV1WByWIdMcpHeartbeat
      x-operation-id-source: derived
  /api/v1/w/{wId}/mcp/register:
    post:
      summary: Register a client-side MCP server
      description: 'Documentation

        Register a client-side MCP server to Dust.

        The registration is scoped to the current user and workspace.

        A serverId identifier is generated and returned in the response.'
      tags:
      - MCP
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serverName
              properties:
                serverName:
                  type: string
                  description: Name of the MCP server
      responses:
        '200':
          description: Server registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  serverId:
                    type: string
                  expiresAt:
                    type: string
                    format: date-time
        '400':
          description: Bad Request. Missing or invalid parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. User does not have access to the workspace.
      operationId: postApiV1WByWIdMcpRegister
      x-operation-id-source: derived
  /api/v1/w/{wId}/mcp/requests:
    get:
      summary: Stream MCP tool requests for a workspace
      description: 'Documentation

        Server-Sent Events (SSE) endpoint that streams MCP tool requests for a workspace.

        This endpoint is used by client-side MCP servers to listen for tool requests in real-time.

        Events arrive as new tool requests are made. Reconnect with `lastEventId` after the stream closes to continue receiving events.

        The stream starts with a `:connect` comment. Request frames carry JSON with `eventId` and `data` fields. A plain-text `data: done` frame ends the current connection; clients may reconnect with `lastEventId`.'
      tags:
      - MCP
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      - in: query
        name: serverId
        required: true
        description: ID of the MCP server to filter events for
        schema:
          type: string
      - in: query
        name: lastEventId
        required: false
        description: Redis stream ID of the last received request event. Omit to start from the available history.
        schema:
          type: string
      responses:
        '200':
          description: 'SSE event stream with a `:connect` comment followed by request frames. The JSON `data` field in each request frame contains the tool request.

            '
          content:
            text/event-stream:
              schema:
                type: object
                required:
                - eventId
                - data
                properties:
                  eventId:
                    type: string
                    description: Redis stream ID used as the resume cursor.
                  data:
                    type: object
                    description: The tool request data
        '400':
          description: Bad Request. Missing or invalid parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. You don't have access to this workspace or MCP server.
        '500':
          description: Internal Server Error.
      operationId: getApiV1WByWIdMcpRequests
      x-operation-id-source: derived
  /api/v1/w/{wId}/mcp/results:
    post:
      summary: Submit MCP tool execution results
      description: 'Documentation

        Endpoint for client-side MCP servers to submit the results of tool executions.

        This endpoint accepts the output from tools that were executed locally.'
      tags:
      - MCP
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: wId
        required: true
        description: ID of the workspace
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - result
              - serverId
              properties:
                result:
                  type: object
                  description: The result data from the tool execution
                serverId:
                  type: string
                  description: ID of the MCP server submitting the results
      responses:
        '200':
          description: Tool execution results successfully submitted
        '400':
          description: Bad Request. Missing or invalid parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. You don't have access to this workspace or MCP server.
        '404':
          description: Conversation or message not found.
        '500':
          description: Internal Server Error.
      operationId: postApiV1WByWIdMcpResults
      x-operation-id-source: derived
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Your DUST API key is a Bearer token.
x-provenance:
  method: harvested
  publisher: Dust
  source: https://raw.githubusercontent.com/dust-tt/dust/refs/heads/main/front-api/public/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)