Skip to main content

Remote MCP OAuth

Claude Directory and other remote MCP clients connect to AIR over Streamable HTTP at https://mcp.air.thalus.ai/mcp. Authorization uses OAuth 2.1 (authorization code + PKCE) on the AIR API, with consent in the AIR portal.

Local stdio users should keep using an API key — see MCP AIR setup.

Connect from Claude​

  1. Open Settings → Connectors → Add custom connector.
  2. Enter https://mcp.air.thalus.ai/mcp and click Connect.
  3. Sign in to AIR if prompted, then pick the domain and access level on the consent screen and approve.
  4. Back in Claude, ask it to run air_list_domains to confirm the connection.

Nothing to install and no API key to create — approving provisions a scoped service-account key held only by the MCP server. Each approval covers one domain; connect again to reach another.

Choose Assessment runner unless you need document uploads, search, portfolio, or project creation, which require Full pipeline. To change level later, reconnect and pick the other preset.

What differs from stdio​

air_run_assessment_from_file and air_run_full_assessment_pipeline are not available remotely — they need a local filesystem and the MCP Tasks extension respectively. Upload with air_upload_document_init → PUT → air_upload_document_complete, and run assessments with air_start_assessment → air_wait_for_assessment → air_get_assessment_summary.

Waits cap at four minutes per call and return ready: false with the current status, because hosted clients abort a tool call at five minutes. A long assessment simply takes several rounds of waiting.

Actors​

PieceHost
MCP tools (HTTP)mcp.air.thalus.ai
OAuth metadata, token, introspection, DCRapi.air.thalus.ai
Consent UI (domain + scope preset)air.thalus.ai/oauth/consent

Endpoints (air-api)​

RoutePurpose
GET /.well-known/oauth-authorization-serverAuthorization server metadata
GET /.well-known/oauth-protected-resourceResource = https://mcp.air.thalus.ai/mcp
POST /oauth/registerDynamic client registration
GET /oauth/authorizeRedirects to portal consent
POST /oauth/tokenAuthorization code + PKCE exchange
POST /oauth/introspectRFC 7662 — MCP host validates access tokens
  1. Client opens /oauth/authorize with client_id, redirect_uri, resource=https://mcp.air.thalus.ai/mcp, code_challenge (S256), and optional state.
  2. User signs in to AIR if needed (returnTo preserves the consent URL).
  3. Consent page lists domains the user owns or administers.
  4. User picks a domain and preset:
    • Assessment runner — run assessments and read projects/domains
    • Full pipeline — also upload documents, search, portfolio, create projects
  5. Approve creates (or rotates) a domain service-account API key, stores a consent grant, and redirects with an authorization code.
  6. Client exchanges the code with the same resource; the response includes a one-hour access token and rotating refresh token.
  7. The MCP host authenticates to introspection, verifies the token audience, and calls the Integrator API with the resolved key.

Refresh tokens expire after 30 days and rotate on every use. Reusing an old refresh token revokes the entire token family.

Assessments and document uploads consume organization credits. Approve only clients you trust.

MCP host auth​

Unauthenticated initialize against the MCP HTTP path returns 401 with:

WWW-Authenticate: Bearer realm="...", resource_metadata="https://api.air.thalus.ai/.well-known/oauth-protected-resource"

Authenticated requests may use:

  • OAuth access token (Directory / Claude.ai), or
  • Raw domain API key Bearer (advanced / Claude Code HTTP)

The introspection response contains the resolved domain API key, so /oauth/introspect requires dedicated HTTP Basic credentials. Configure the API with AIR_MCP_INTROSPECT_CLIENT_ID / AIR_MCP_INTROSPECT_CLIENT_SECRET and the MCP host with matching OAUTH_INTROSPECT_CLIENT_ID / OAUTH_INTROSPECT_CLIENT_SECRET values. Do not use a dynamically registered OAuth client for introspection.

Revocation (v1)​

Revoke access from Connected apps in the portal (domain → Connected apps), or revoke the underlying domain API key under API Keys.