Unify and manage your data

Authentication flow for the AgentFlow MCP Server

Learn how the AgentFlow MCP Server uses OAuth 2.0 with PKCE to authorize client access to context-aware tools.

The AgentFlow MCP Server uses OAuth 2.0 Authorization Code Flow with PKCE to authenticate users and agents. This flow ensures secure, auditable, and context-aware access to Reltio APIs. All interactions with MCP tools require a valid access token issued by the Reltio Authentication Server.

The following are the key behaviors:
  • Tokens are tenant-scoped and short-lived for secure session control.
  • Only users with the ROLE_EXECUTE_MCP role or any role that includes the agentflow.mcp.EXECUTE permission can invoke MCP tools. Require provisioning by your tenant administrator.
  • All API calls are governed by Reltio's Permissions Framework and logged in the Activity Log.
  • PKCE ensures compatibility with both browser and headless agent clients.

Authentication workflow

Important: The OAuth 2.0 flow — including Proof Key for Code Exchange (PKCE) and token exchange — is handled entirely by the MCP Client. The Reltio MCP Server requires a valid access token but does not participate in the authentication process.
Note: This workflow shows the full OAuth 2.0 Authorization Code Flow with PKCE, which is typically used by browser-based and interactive clients. If you're using a different authentication method — like the client credentials flow — you can get an access token separately and start using MCP tools right away. In that case, skip directly to Step 10: MCP tool access (authenticated).

The following sequence explains each step in the diagram above, illustrating how an AI agent securely authenticates and interacts with the Reltio MCP Server using OAuth 2.0 and PKCE:
  1. User prompt: A user agent (browser) initiates the flow with a user prompt. The MCP client picks up this prompt and initiates tool discovery via the LLM.

  2. Tool discovery: The MCP client communicates with the LLM to find an appropriate tool using the Tool Find API (Message API). Once identified, the MCP tool is selected.

  3. MCP tool access attempt (without token): The MCP client tries to invoke the MCP tool by calling the AgentFlow MCP Server. Since no token is provided, it receives a 401 Unauthorized response with a WWW-Authenticate header pointing to the OAuth discovery endpoint.

  4. OAuth discovery: The MCP client sends a GET request to the OAuth metadata endpoint. The server responds with supported endpoints and methods.

  5. PKCE generation: The MCP client generates a code_challenge and code_verifier as part of the Proof Key for Code Exchange (PKCE) process.

  6. User redirection to authorization: The MCP client constructs an authorization URL including the code_challenge and redirects the user (via browser) to the Reltio Auth Server.

  7. User authentication: The Reltio Auth Server prompts the user to sign in and approve access.

  8. Redirect with authorization code: After successful login, the user is redirected back to the client’s callback URL along with the authorization_code.

  9. Token exchange: The MCP client exchanges the authorization_code and code_verifier for an access token from the Reltio Auth Server.

  10. MCP tool access (authenticated): The MCP client resends the request to the MCP Server, this time including the access token.

  11. Token validation: The MCP Server validates the access token by calling the checkToken endpoint on the Reltio Auth Server.

  12. Final tool invocation: With the token validated, the MCP Server invokes the corresponding Reltio API.

  13. Response to user: The MCP Server sends the response to the MCP client, which relays it to the user agent (browser).

Authentication components

ComponentDescription
User Agent (Browser)Handles the user-facing portion of the OAuth flow, including login and consent via the Auth Server.
MCP ClientInitiates tool discovery, generates PKCE values, redirects users to authenticate, and exchanges codes for tokens. Examples include LangChain apps, Jupyter notebooks, and command-line scripts using the MCP SDK.
LLMAssists in tool discovery based on the user prompt. Examples include Claude and ChatGPT integrated into agent workflows.
Reltio AgentFlow MCP ServerProcesses tool requests, validates tokens, and invokes Reltio APIs on behalf of authenticated clients.
Reltio Auth ServerAuthenticates users, issues tokens, and validates access tokens during MCP requests.
Reltio APISecured downstream endpoints that provide core MDM functions such as entity resolution and data enrichment.