Skip to main content

How to Register and Verify an AtomicMCP OAuth App

Use this procedure when connecting an internal application, agent, automation, or another MCP-compatible product to AtomicMCP.

Before you begin​

Your client must support:

  • MCP Streamable HTTP.
  • OAuth Authorization Code flow.
  • PKCE using S256.
  • Bearer access tokens and refresh-token rotation.
  • A stable HTTPS callback URL.

Native apps may use an approved loopback callback during development. Production web callbacks must use HTTPS.

Step 1: Prepare the callback​

Choose the exact callback URL handled by your application, for example:

https://your-app.example.com/oauth/atomicat/callback

AtomicMCP performs exact callback matching. Scheme, hostname, path, port, and trailing slash must match the registered value.

Step 2: Create the OAuth app​

  1. Sign in to Atomicat.
  2. Open Settings → Integrations.
  3. Under AtomicMCP OAuth Apps, select Create app.
  4. Enter the app name and exact callback URL.
  5. Select the maximum scopes the app may request.
  6. Save the app.

Copy the generated Client ID, verification URL, and verification JSON.

Step 3: Publish the verification document​

At every callback origin, serve the exact generated JSON from:

https://your-app.example.com/.well-known/atomicat-oauth-client.json

The response has this shape:

{
  "clientId": "app_generated_client_id",
  "challenge": "generated_domain_challenge"
}

Return JSON over HTTPS without authentication or redirects. The values must exactly match the app shown in Atomicat.

Step 4: Verify the app​

Return to Settings → Integrations and select Verify. Atomicat checks every callback origin. Fix any reported DNS, TLS, HTTP, or JSON mismatch before continuing.

Step 5: Configure OAuth​

Configure the client with:

Authorization endpoint: https://mcp.atomicat.com.br/oauth/authorize
Token endpoint:         https://mcp.atomicat.com.br/oauth/token
Revocation endpoint:    https://mcp.atomicat.com.br/oauth/revoke
MCP endpoint:           https://mcp.atomicat.com.br/mcp
Resource:               https://mcp.atomicat.com.br
Client type:            Public
PKCE method:            S256

Request only the scopes needed by the integration. For example:

sites pages

The app must allow every requested scope. Allowed scopes are a ceiling, not an automatic grant.

Step 6: Complete authorization​

  1. Generate a cryptographically random state and PKCE verifier.
  2. Redirect the user to the authorization endpoint with the Client ID, exact callback, explicit scopes, resource, state, and S256 challenge.
  3. Validate state in the callback.
  4. Exchange the one-time code with the original PKCE verifier.
  5. Keep access and refresh tokens on the server whenever possible.

Step 7: Test the MCP lifecycle​

Using an official MCP SDK:

  1. Connect to the Streamable HTTP endpoint with the access token.
  2. Complete initialize and the initialized notification.
  3. Call tools/list and confirm only the granted scope groups are exposed.
  4. Call a low-risk read tool.
  5. Test refresh-token rotation.
  6. Disconnect the app in Atomicat and confirm the next MCP request fails immediately.
  7. Authorize again and confirm the connection works.

Updating scopes or callbacks​

  • Added scopes: update the client's requested scopes, disconnect, and authorize again.
  • Removed scopes: disconnect existing grants immediately, then authorize again.
  • Changed callback: publish the verification document on the new origin, update the app, and verify it again.

FAQ​

Why does my token contain fewer scopes than the app allows?

Tokens receive the valid scopes explicitly requested during authorization. The app's allowed scopes only define the maximum requestable set.

Why did verification fail?

Confirm the well-known URL uses HTTPS, is public, returns JSON directly, and contains the exact Client ID and challenge generated for that app.

Must I reconnect after changing scopes?

Yes. Existing grants keep their original scopes. Disconnect and authorize again with the updated request.