Public MCP OAuth provisioning

The public MCP endpoint is https://mcp.proximal.energy/mcp. Clerk authenticates the human user's identity and client they are using, for example Claude or Codex. The public AgentCore Gateway validates the Clerk access token, and its request interceptor exchanges that token for a short-lived, KMS-signed Mono delegation token. The original Clerk credential stops at the Gateway. Mono authorizes the actual operation and the user's access to its project and resources.

Web-app authentication flow:

• User → Aria web app → Clerk sign-in → Clerk session → Aria

MCP authentication flow:

• User → Client → Clerk sign-in → Oauth Token → Agentcore Gateway

Clerk instances and current setup

As of September 23, 2026, both instances require authorization code with S256 PKCE, issue signed OAuth access tokens, are configured to include an audience when the client requests a resource, and have a configured Clerk Account Portal for sign-in and consent. Both advertise Client ID Metadata Document support and admit only pre-registered clients. Dynamic client registration is disabled. Clerk adds offline_access to Client ID Metadata Document clients.

The default custom scopes for clients that omit scope are mcp:connect and endpoint:read. No write scope is defined or granted for the initial release. Both custom scopes are Advertised in Clerk, and each reviewed client is limited to them. Clerk also requires offline_access for these clients.

The interceptor must explicitly allowlist this external-to-internal mapping and use only scopes Clerk actually granted. Unknown or ungranted scopes confer no Mono authority. The validated OAuth client_id must map to a canonical client value: https://chatgpt.com/oauth/client.json to chatgpt, and https://claude.ai/oauth/claude-code-client-metadata to claude-code. Do not derive client identity from request headers, tool arguments, or the token audience. The delegation token names the user, trusted actor, canonical client, allowed scopes, and request identifiers; it does not need a predetermined MCP tool claim. Mono resolves the actual operation before checking its required scope. Every initial read-only operation requires endpoint:read.

Deployment inputs

The following non-secret Parameter Store values are in us-east-2:

Clerk places the requested OAuth resource in the access token's aud claim. Clients must request the public MCP resource above; the Gateway validates that exact audience. Staging still needs a stable resource URL before /auth/clerk/staging/mcp-audience can be set. The interceptor stacks also need /auth/mono-delegation/{staging,prod}/issuer and /auth/mono-delegation/{staging,prod}/audience, coordinated with Mono's token validator. The signing keys are created by the interceptor stacks.

Client admission

For each new client, review its HTTPS Client ID Metadata Document, redirect URIs, and token authentication method. Pre-register the exact document URL in Clerk's OAuth applications > Applications tab, assign only mcp:connect and endpoint:read, and add the exact client ID to the Gateway allowed-client parameter. Clerk's settings must keep admission at Pre-registered clients only. Enable dynamic client registration only if a required client cannot use a metadata document or a manually registered client ID; it exposes a public registration endpoint.

ChatGPT publishes https://chatgpt.com/oauth/client.json, which was reviewed and pre-registered. Clerk provides a Claude Code preset. Cursor has not been registered: establish its current registration method and redirect URI before adding it. A custom client likewise needs a published metadata document or a manually registered client ID. Neither client should be added to the Gateway allowed-client list before its Clerk configuration is reviewed.

Remaining work

The two custom scopes, default grants, and ChatGPT/Claude Code registrations are configured in both Clerk instances. Authorization-server discovery has been checked for both issuers: it advertises those two custom scopes and metadata- document support, and no dynamic registration endpoint. This does not yet verify sign-in, token issuance, or MCP connectivity. The unchecked items below are the remaining work; task numbers refer to aria/scaffold.md.

Configuration and deployment

• Choose the stable staging MCP resource URL and set /auth/clerk/staging/mcp-audience in us-east-2. Clients must request that exact URL as their OAuth resource.
• Agree on the Mono delegation issuer and audience for staging and production, then set /auth/mono-delegation/{staging,prod}/{issuer,audience} in us-east-2. Match these values in the token issuer and Mono validator.
• Complete Mono's delegation settings, verification-key injection, token validation, delegated-agent authentication, project-access cache, request identity, operation-level endpoint:read enforcement, and request-context wiring (Tasks 8-16). Normal Clerk and API-key callers must retain their existing behavior.
• Complete the single shared MCP server and canonical read-only tool registry: package the plugin, use one Mono client and trusted delegation path, require explicit project_id on project tools, add project discovery and generated read tools, and serve both Gateways from the same Runtime (Tasks 17-26). Do not expose mutating or dashboard-only tools.
• Bind Aria's trusted current project into the same canonical tools without changing their public schemas, and verify the shared Runtime, catalog, scope coverage, and credential propagation (Tasks 27-29).
• Add non-blocking MCP telemetry storage and instrumentation without storing credentials or treating telemetry as audit history (Tasks 30-32).
• Replace raw Clerk-token forwarding in internal Aria with project-bound delegation and complete its shared MCP execution path (Tasks 33-35).
• Deploy the shared MCP service and Mono changes, then the staging and production interceptor, Gateway, and target-sync stacks. Deploy the production public edge stack in us-east-1; these seven public MCP stacks are not deployed yet. Confirm pipeline dependencies and stack outputs before exposing the endpoint.

Client admission

• Establish Cursor's current registration method and redirect URI. Review it, register it in Clerk, grant only mcp:connect and endpoint:read, and add its exact client ID to the Gateway allowlist.
• Do the same for at least one custom MCP client. Keep dynamic registration disabled unless a required client cannot use a metadata document or manually registered client ID.

Launch verification

• Fetch https://mcp.proximal.energy/.well-known/oauth-protected-resource/mcp after the edge deploys; confirm the resource URL and Clerk authorization server. Check the equivalent staging metadata at its chosen URL.
• Complete sign-in, consent, callback, and token issuance with ChatGPT and Claude Code in staging and production. Verify the issued token's signature, issuer, audience, client ID, subject, and the two granted MCP scopes. Starting an authorization redirect alone is insufficient.
• Confirm the Gateway rejects a missing mcp:connect, an unregistered client, a wrong audience, and an unsigned token. Confirm every read-only tool requires endpoint:read, reaches Mono with only the internal delegation token, and still obeys the user's current project and resource permissions.
• Run production MCP connectivity and canonical-tool-catalog checks with ChatGPT, Claude Code, Cursor, and the custom client (Task 36).
• Confirm internal Aria still works through its existing Gateway and shared Runtime using project-bound delegation, not a raw Clerk token (Task 37).
• Verify the validated execution context needed for future auditing survives the full request path; do not implement audit storage yet (Task 38).

There is one canonical MCP tool registry and one shared Runtime per environment. The initial canonical tools are read-only. Dashboard-only capabilities remain agent built-ins and never appear in MCP tool discovery. ClickHouse holds asynchronous operational telemetry, not authoritative audit history. Authoritative auditing is deferred; the validated request context must remain available for it later.

See Clerk's OAuth setup, Clerk's metadata-document guide, and AgentCore's inbound token validation.