> ## 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.

# Finish connecting an MCP server with OAuth

> Finishes an OAuth connection with the authorization response the browser brought back. Only the user who started it finishes it, while still a member of the server's organization (and, for the organization's connection, an owner or admin); a response finished in another user's session is refused before its code is redeemed. The outcome is a typed status; the grant is stored encrypted when it is connected. It names the start's return_to when the state opened, for the callback page to go there with it.



## OpenAPI

````yaml api-reference/openapi.v1.json POST /mcp-servers/oauth/callback
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/oauth/callback:
    post:
      tags:
        - mcp-servers
      summary: Finish connecting an MCP server with OAuth
      description: >-
        Finishes an OAuth connection with the authorization response the browser
        brought back. Only the user who started it finishes it, while still a
        member of the server's organization (and, for the organization's
        connection, an owner or admin); a response finished in another user's
        session is refused before its code is redeemed. The outcome is a typed
        status; the grant is stored encrypted when it is connected. It names the
        start's return_to when the state opened, for the callback page to go
        there with it.
      operationId: finishMcpServerOAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinishMcpServerOAuthRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerOAuthOutcome'
          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:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          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:
    FinishMcpServerOAuthRequest:
      additionalProperties: false
      properties:
        code:
          maxLength: 4096
          type: string
        error:
          maxLength: 256
          type: string
        iss:
          description: >-
            The response's iss parameter (RFC 9207), exactly as received;
            omitted when the response carried none.
          maxLength: 2048
          type: string
        state:
          maxLength: 8192
          minLength: 1
          type: string
      required:
        - state
      type: object
    McpServerOAuthOutcome:
      additionalProperties: false
      properties:
        mcp_server_id:
          format: uuid
          type:
            - string
            - 'null'
        oauth_error:
          pattern: ^[A-Za-z0-9_.-]{1,64}$
          type:
            - string
            - 'null'
        return_to:
          description: >-
            The Aether mobile app's deep link the start asked to end at, for the
            callback page to go there with this outcome. Null when the start
            named none, or when the state could not be opened.
          enum:
            - aether://mcp-connected
          type:
            - string
            - 'null'
        status:
          enum:
            - connected
            - invalid_state
            - state_expired
            - other_user
            - not_authorized
            - iss_mismatch
            - authorization_failed
            - exchange_failed
            - token_invalid
            - server_changed
            - oauth_app_deleted
          type: string
      required:
        - status
        - mcp_server_id
        - oauth_error
        - return_to
      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
    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

````

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