> ## 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 for the organization

> Org admins only. Starts the organization's connection to a server that authenticates with OAuth, granted with your consent, or its reconnection, and returns the authorization URL to send your browser to. Projects may then use the org credential policy for the server.



## OpenAPI

````yaml api-reference/openapi.v1.json POST /mcp-servers/{mcpServerID}/org-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}/org-connection/oauth:
    post:
      tags:
        - mcp-servers
      summary: Connect an MCP server with OAuth for the organization
      description: >-
        Org admins only. Starts the organization's connection to a server that
        authenticates with OAuth, granted with your consent, or its
        reconnection, and returns the authorization URL to send your browser to.
        Projects may then use the org credential policy for the server.
      operationId: startOrgMcpServerOAuth
      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
            - mcp_oauth_app_issuer_invalid
            - mcp_oauth_app_invalid
            - mcp_oauth_app_auth_method_unsupported
          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

````