> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Start an MCP OAuth install probe

> Start OAuth for a candidate MCP server and return the authorization URL.



## OpenAPI

````yaml /openapi/agent-sdk.json post /api/mcp/oauth/start
openapi: 3.1.0
info:
  description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
  title: OpenHands Agent Server
  version: 1.52.0
servers: []
security: []
paths:
  /api/mcp/oauth/start:
    post:
      tags:
        - MCP
      summary: Start an MCP OAuth install probe
      description: Start OAuth for a candidate MCP server and return the authorization URL.
      operationId: start_mcp_oauth_api_mcp_oauth_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPTestRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPOAuthStartResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - APIKeyHeader: []
components:
  schemas:
    MCPTestRequest:
      description: Body for ``POST /api/mcp/test``.
      properties:
        name:
          default: test-server
          description: >-
            Name to use for the server inside the temporary MCP server map. Only
            affects error messages -- does not need to match any persisted
            setting.
          maxLength: 128
          minLength: 1
          title: Name
          type: string
        server:
          discriminator:
            mapping:
              http: '#/components/schemas/_RemoteMCPServerSpec'
              shttp: '#/components/schemas/_RemoteMCPServerSpec'
              sse: '#/components/schemas/_RemoteMCPServerSpec'
              stdio: '#/components/schemas/_StdioMCPServerSpec'
              streamable-http: '#/components/schemas/_RemoteMCPServerSpec'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/_StdioMCPServerSpec'
            - $ref: '#/components/schemas/_RemoteMCPServerSpec'
          title: Server
        timeout:
          default: 15
          description: Seconds to wait for connection + tools/list to complete.
          exclusiveMinimum: 0
          maximum: 120
          title: Timeout
          type: number
        tool_call:
          anyOf:
            - $ref: '#/components/schemas/MCPToolCallSpec'
            - type: 'null'
          description: >-
            Optional read-only tool to invoke after listing succeeds, so callers
            can verify credentials the server only exercises on tool invocation.
            Its outcome is reported verbatim in `tool_result` without affecting
            `ok`.
      required:
        - server
      title: MCPTestRequest
      type: object
    MCPOAuthStartResponse:
      description: Response for starting an install-time OAuth MCP probe.
      properties:
        authorization_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Authorization Url
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        error_kind:
          anyOf:
            - enum:
                - timeout
                - connection
                - unknown
              type: string
            - type: 'null'
          title: Error Kind
        job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Job Id
        ok:
          title: Ok
          type: boolean
      required:
        - ok
      title: MCPOAuthStartResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    _RemoteMCPServerSpec:
      description: Legacy remote MCP server spec accepted by the public REST API.
      properties:
        auth:
          anyOf:
            - discriminator:
                mapping:
                  api_key: '#/components/schemas/MCPApiKeyAuthCredential-Input'
                  basic: '#/components/schemas/MCPBasicAuthCredential-Input'
                  bearer: '#/components/schemas/MCPBearerAuthCredential-Input'
                  header: '#/components/schemas/MCPHeaderAuthCredential-Input'
                  none: '#/components/schemas/MCPNoneAuthCredential'
                  oauth2: '#/components/schemas/MCPOAuthAuthCredential-Input'
                propertyName: strategy
              oneOf:
                - $ref: '#/components/schemas/MCPNoneAuthCredential'
                - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input'
                - $ref: '#/components/schemas/MCPBearerAuthCredential-Input'
                - $ref: '#/components/schemas/MCPBasicAuthCredential-Input'
                - $ref: '#/components/schemas/MCPHeaderAuthCredential-Input'
                - $ref: '#/components/schemas/MCPOAuthAuthCredential-Input'
            - type: 'null'
          title: Auth
        headers:
          additionalProperties:
            type: string
          title: Headers
          type: object
        keep_alive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Keep Alive
        sse_read_timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Sse Read Timeout
        timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Timeout
        type:
          enum:
            - http
            - shttp
            - streamable-http
            - sse
          title: Type
          type: string
        url:
          minLength: 1
          title: Url
          type: string
      required:
        - type
        - url
      title: _RemoteMCPServerSpec
      type: object
    _StdioMCPServerSpec:
      description: Legacy stdio MCP server spec accepted by the public REST API.
      properties:
        args:
          items:
            type: string
          title: Args
          type: array
        command:
          description: Executable to invoke
          minLength: 1
          title: Command
          type: string
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
        env:
          additionalProperties:
            type: string
          title: Env
          type: object
        type:
          const: stdio
          default: stdio
          title: Type
          type: string
      required:
        - command
      title: _StdioMCPServerSpec
      type: object
    MCPToolCallSpec:
      description: |-
        A single tool invocation to run as part of the connection test.

        Listing tools does not exercise the credentials many servers only use
        inside tool handlers, so callers can name one tool to invoke after the
        listing succeeds. Callers are responsible for choosing a read-only tool;
        the endpoint executes it verbatim.
      properties:
        arguments:
          additionalProperties: true
          description: Arguments passed to the tool unchanged.
          title: Arguments
          type: object
        name:
          description: Name of the tool to invoke
          minLength: 1
          title: Name
          type: string
      required:
        - name
      title: MCPToolCallSpec
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    MCPApiKeyAuthCredential-Input:
      properties:
        header_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Header Name
        strategy:
          const: api_key
          title: Strategy
          type: string
        value:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPApiKeyAuthCredential
      type: object
    MCPBasicAuthCredential-Input:
      properties:
        password:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Password
        strategy:
          const: basic
          title: Strategy
          type: string
        username:
          title: Username
          type: string
      required:
        - strategy
        - username
      title: MCPBasicAuthCredential
      type: object
    MCPBearerAuthCredential-Input:
      properties:
        strategy:
          const: bearer
          title: Strategy
          type: string
        value:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPBearerAuthCredential
      type: object
    MCPHeaderAuthCredential-Input:
      properties:
        headers:
          additionalProperties:
            format: password
            type: string
            writeOnly: true
          title: Headers
          type: object
        strategy:
          const: header
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPHeaderAuthCredential
      type: object
    MCPNoneAuthCredential:
      properties:
        strategy:
          const: none
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPNoneAuthCredential
      type: object
    MCPOAuthAuthCredential-Input:
      properties:
        authentication:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthAuthentication-Input'
            - type: 'null'
        state:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthState-Input'
            - type: 'null'
        strategy:
          const: oauth2
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPOAuthAuthCredential
      type: object
    MCPOAuthAuthentication-Input:
      additionalProperties: false
      properties:
        additional_client_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Client Metadata
        client_auth_method:
          anyOf:
            - enum:
                - none
                - client_secret_post
                - client_secret_basic
                - private_key_jwt
              type: string
            - type: 'null'
          title: Client Auth Method
        client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Id
        client_metadata_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Metadata Url
        client_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Name
        client_secret:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Client Secret
        scopes:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scopes
        type:
          const: oauth
          title: Type
          type: string
      required:
        - type
      title: MCPOAuthAuthentication
      type: object
    MCPOAuthState-Input:
      properties:
        client_info:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthClientInfoState-Input'
            - type: 'null'
        token_expires_at:
          anyOf:
            - type: number
            - type: 'null'
          title: Token Expires At
        tokens:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthTokenState-Input'
            - type: 'null'
      title: MCPOAuthState
      type: object
    MCPOAuthClientInfoState-Input:
      additionalProperties: true
      properties:
        client_secret:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Client Secret
      title: MCPOAuthClientInfoState
      type: object
    MCPOAuthTokenState-Input:
      additionalProperties: true
      properties:
        access_token:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Access Token
        refresh_token:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Refresh Token
      title: MCPOAuthTokenState
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-Session-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.