> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP server with OAuth

> Starts your own connection to a server that authenticates with OAuth, or its reconnection: discovers its authorization server, chooses Aether's client identity there, and returns the authorization URL to send your browser to. The authorization server returns the browser to the web app, which finishes the connection with finishMcpServerOAuth in your session.



## OpenAPI

````yaml api-reference/openapi.v1.json POST /mcp-servers/{mcpServerID}/connection/oauth
openapi: 3.1.0
info:
  title: Aether Public API
  version: 0.1.0
  description: >-
    The versioned, public Aether REST API. Authenticate with an `aether_`
    platform API key or a session token.
servers:
  - url: https://api.runaether.dev/v1
security:
  - bearerAuth: []
paths:
  /mcp-servers/{mcpServerID}/connection/oauth:
    post:
      tags:
        - mcp-servers
      summary: Connect an MCP server with OAuth
      description: >-
        Starts your own connection to a server that authenticates with OAuth, or
        its reconnection: discovers its authorization server, chooses Aether's
        client identity there, and returns the authorization URL to send your
        browser to. The authorization server returns the browser to the web app,
        which finishes the connection with finishMcpServerOAuth in your session.
      operationId: startMcpServerOAuth
      parameters:
        - in: path
          name: mcpServerID
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMcpServerOAuthRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerOAuthAuthorization'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/McpServerErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
components:
  schemas:
    StartMcpServerOAuthRequest:
      additionalProperties: false
      properties:
        url:
          description: >-
            The server URL the connection is started for, as the catalog showed
            it. Refused with mcp_connection_server_changed when the server's URL
            is now another.
          maxLength: 2048
          minLength: 1
          type: string
      required:
        - url
      type: object
    McpServerOAuthAuthorization:
      additionalProperties: false
      properties:
        authorization_url:
          format: uri
          type: string
      required:
        - authorization_url
      type: object
    ErrorResponse:
      additionalProperties: false
      properties:
        code:
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    McpServerErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - mcp_server_key_invalid
            - mcp_server_key_reserved
            - mcp_server_key_taken
            - mcp_server_display_name_invalid
            - mcp_server_url_invalid
            - mcp_server_runtime_invalid
            - mcp_server_package_invalid
            - mcp_server_version_unpinned
            - mcp_server_args_invalid
            - mcp_server_env_invalid
            - mcp_server_kind_change_refused
            - mcp_server_address_refused
            - mcp_server_unreachable
            - mcp_server_not_mcp
            - mcp_server_auth_unsupported
            - mcp_server_auth_discovery_failed
            - mcp_server_response_too_large
            - mcp_server_auth_change_conflict
            - mcp_credential_policy_required
            - mcp_credential_policy_not_applicable
            - mcp_credential_policy_org_unavailable
            - mcp_server_api_key_not_applicable
            - mcp_connection_static_secret_not_accepted
            - mcp_connection_secret_invalid
            - mcp_connection_server_changed
            - mcp_server_aether_managed
            - mcp_connection_github_not_connected
            - mcp_connection_org_not_offered
            - mcp_server_headers_invalid
            - mcp_connection_oauth_not_accepted
            - mcp_oauth_not_advertised
            - mcp_oauth_pkce_unsupported
            - mcp_oauth_app_required
            - mcp_oauth_registration_failed
            - mcp_server_plugin_bundled
            - mcp_repo_config_invalid
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````