Vertesia Remote MCP Connections API

openapi: 3.2.0
info:
  title: Vertesia Remote MCP Connections API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Remote MCP Connections
  description: Remote MCP Connection endpoints manage OAuth discovery, authorization, connection status, and token access for third-party MCP tool collections installed through apps.
paths:
  /remote-mcp-connections/metadata/{app_install_id}/{collection_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: GetRemoteMcpConnectionMetadata
      tags:
      - Remote MCP Connections
      summary: Retrieve remote MCP OAuth metadata
      description: Fetches OAuth authorization-server metadata for an OAuth-enabled MCP collection installed through an app.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth metadata discovered for the MCP collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthMetadataResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: getMetadata
  /remote-mcp-connections/authorize/{app_install_id}/{collection_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: AuthorizeRemoteMcpConnection
      tags:
      - Remote MCP Connections
      summary: Authorize a remote MCP connection
      description: Starts the OAuth flow for an OAuth-enabled MCP collection and returns the authorization URL or immediate connected status.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authorization URL or immediate connection result for the MCP collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthorizeResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: authorize
  /remote-mcp-connections/status/{app_install_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListRemoteMcpConnectionStatuses
      tags:
      - Remote MCP Connections
      summary: List remote MCP connection statuses
      description: Returns authentication status for all OAuth and API-key MCP collections in an installed app.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authentication statuses for the app MCP collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthStatusArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: getStatus
  /remote-mcp-connections/status/{app_install_id}/{collection_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: GetRemoteMcpConnectionStatus
      tags:
      - Remote MCP Connections
      summary: Retrieve a remote MCP connection status
      description: Returns authentication status for a specific OAuth or API-key MCP collection.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authentication status for the MCP collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthStatus'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: getCollectionStatus
  /remote-mcp-connections/connect/{app_install_id}/{collection_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: ConnectRemoteMcpConnection
      tags:
      - Remote MCP Connections
      summary: Connect a remote MCP collection
      description: Obtains and stores a client-credentials token for a remote MCP collection linked to a client-credentials OAuth provider.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Connection result for the MCP collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthConnectResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: connect
  /remote-mcp-connections/token:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: GetRemoteMcpConnectionToken
      tags:
      - Remote MCP Connections
      summary: Retrieve a remote MCP access token
      description: Gets or refreshes an OAuth access token for a remote MCP collection using either an app-installation collection reference or a legacy MCP server URL.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters: []
      responses:
        '200':
          description: Access token for the remote MCP connection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthTokenResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: getToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpOAuthTokenRequest'
  /remote-mcp-connections/disconnect/{app_install_id}/{collection_id}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    delete:
      operationId: DisconnectRemoteMcpConnection
      tags:
      - Remote MCP Connections
      summary: Disconnect a remote MCP collection
      description: Deletes stored OAuth tokens for a remote MCP collection and disconnects the current authentication state.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters:
      - name: app_install_id
        in: path
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Disconnection result for the MCP collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthDisconnectResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/remote-mcp-connections.ts
        className: RemoteMcpConnectionsResource
        methodName: disconnect
components:
  schemas:
    McpOAuthDisconnectResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
      - success
      - message
      additionalProperties: false
    JSONValue: {}
    JSONObject:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JSONValue'
    McpOAuthTokenResponse:
      type: object
      properties:
        access_token:
          type: string
      required:
      - access_token
      additionalProperties: false
    McpOAuthConnectResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    OAuthAuthorizeResponse:
      type: object
      properties:
        authorization_url:
          type: string
        state:
          type: string
        connected:
          type: boolean
      additionalProperties: false
      description: Response from OAuth authorization endpoint
    OAuthMetadataResponse:
      type: object
      properties:
        collection_id:
          type: string
        collection_name:
          type: string
        mcp_server_url:
          type: string
        metadata:
          $ref: '#/components/schemas/JSONObject'
      required:
      - collection_id
      - collection_name
      - mcp_server_url
      - metadata
      additionalProperties: false
      description: Response from OAuth metadata endpoint
    OAuthAuthStatusArray:
      type: array
      items:
        $ref: '#/components/schemas/OAuthAuthStatus'
    McpOAuthTokenRequest:
      type: object
      properties:
        app_install_id:
          type: string
        collection_id:
          type: string
        mcp_server_url:
          type: string
      additionalProperties: false
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    OAuthAuthStatus:
      type: object
      properties:
        collection_id:
          type: string
        collection_name:
          type: string
        authenticated:
          type: boolean
        mcp_server_url:
          type: string
        expires_at:
          type: string
        scope:
          type: string
      required:
      - collection_id
      - collection_name
      - authenticated
      - mcp_server_url
      additionalProperties: false
      description: OAuth authentication status for an MCP tool collection
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections