Authorization

The MCP server uses OAuth 2.1 for authorization. Every supported client performs a one-time browser-based authorization flow. The flow is fully automatic. You do not need to configure tokens or secrets manually.

First-time authorization

When you connect a client for the first time:

  1. The client contacts the MCP server and is redirected to start the OAuth flow.

  2. Your default browser opens on the Neptune DXP - Open Edition sign-in page. Sign in with your credentials.

  3. After sign-in, a consent page is shown. The consent page lists:

    • The name of the client application.

    • The scope being requested (mcp:tools).

    • The hostname of the redirect URL.

  4. Select Approve to grant access, or Deny to refuse. After approval, the client receives an access token and a refresh token, and the connection is ready to use. If you deny, the client is not granted access and no token is issued.

The consent page is protected against tampering. It cannot be embedded in an iframe, and it includes a single-use cross-site request forgery token.

Always approve consent from a window that you opened yourself.

Token lifetime

The MCP server uses short-lived access tokens and longer-lived refresh tokens:

Token Validity Notes

Access token

1 hour

Used on each request to /mcp. The client refreshes it automatically before it expires.

Refresh token

7 days

Used to obtain a new access token. The refresh token is rotated on every use.

Client secret (optional)

30 days

Only set when the registered client uses one.

When the refresh token expires, the client must repeat the authorization flow. Remove and re-add the server to trigger a fresh sign-in.

Revoking access

To revoke a client’s access:

  • Remove the server entry from the client (for example, claude mcp remove planet9). The next refresh attempt will fail and the client will be locked out.

  • Or, if the client supports it, call the revocation endpoint of the MCP server. The server invalidates the refresh token immediately and rejects further use of the related access token.

Changing the public URL of the MCP server invalidates every existing session. After such a change, all connected clients must repeat the authorization flow. Schedule URL changes during a maintenance window if you have many active clients.

Related topics