MCP Flip Identity Provider Guide
Guide how to connect an MCP server to Flip Ask AI with Flip as identity provider, so the MCP server receives a Flip access token for each user
This guide explains how to connect an MCP server to Flip Ask AI with Flip as identity provider. With this setup, the MCP server trusts Flip directly: for every Flip user who talks to a custom agent, Flip issues a short-lived access token for that user and sends it to the MCP server. The MCP server validates the token and applies the permissions of that user.
The guide is written for two readers at once:
- the team operating the MCP server (or an MCP gateway in front of it), who needs to validate Flip's access tokens
- the Flip administrator who creates the OIDC client and the MCP connector in the admin console
If your MCP server is protected by your own authorization server that issues the access tokens, see the MCP Enterprise-Managed Authorization Guide instead.
How it works
- The OIDC client lives in Flip. A Flip administrator creates an OIDC client in the admin console and allows Ask AI to exchange tokens for it. When they register your MCP server in Flip, they select that client.
- Flip issues the token. For tool discovery and every tool call on your MCP server, Ask AI exchanges the chatting user's Flip token for an access token whose audience (
aud) is theclient_idof that OIDC client. Flip sends it asAuthorization: Bearer <token>. - Your MCP server accepts Flip as a trusted issuer, next to any identity provider it already trusts. It validates issuer, audience and signature, maps the user from the token's claims (for example
suboremail) and applies that user's permissions.
Prerequisites
- Your MCP server can validate JWT bearer tokens from an additional issuer. It needs to check the issuer, the audience and the signature against Flip's published keys. See Validating the access token on your side.
- Your users have a matching identity on your side. The token identifies the user by Flip's user ID (
sub), their email address (email) and their Flip username (preferred_username). Whichever claim you use must be resolvable to an account in your system for every user who should use the MCP server.
Information to exchange
What Flip provides to the MCP server
| Value | Where to find it |
|---|---|
| Flip issuer | https://{domain}/auth/realms/{organisation-id}. Becomes the iss claim of every access token. See Flip issuer. |
| Discovery document | https://{domain}/auth/realms/{organisation-id}/.well-known/openid-configuration |
| JWKS endpoint | https://{domain}/auth/realms/{organisation-id}/protocol/openid-connect/certs. Also listed as jwks_uri in the discovery document. |
| Audience | The Client ID of the OIDC client created in Flip. Becomes the aud claim of every access token. |
The same endpoints are described in more detail in the OIDC Public Client Implementation Guide.
What the MCP server provides to Flip
| Value | Notes |
|---|---|
| MCP server URL | The URL the administrator enters on the MCP connector. |
| User mapping | Which claim your MCP server uses to identify the user (sub, email or preferred_username). Flip does not need this value, but the administrator needs it to check that every user has a matching identity. |
You can prepare the validation on your side before the client exists in Flip. Agree on a client_id in advance, or create a test client in a test environment.
Setup in the Flip admin console
Step 1: Create the OIDC client
In the admin console, open Access & security → OIDC clients and choose Create OIDC client.
| Field | What to enter |
|---|---|
| Client ID | The value your MCP server validates as audience, for example my-mcp-server. Lowercase letters, digits and single hyphens. It cannot be changed later. |
| Name | A display name, for example the name of the MCP server. |
Under Token exchange, choose Add client and select Ask AI as Allowed Flip client. Only OIDC clients that allow Ask AI are offered in the MCP connector in step 2.
Step 2: Create the MCP connector
Create or edit a custom agent and add an MCP connector for your MCP server as described in How to Set Up Custom Agents with MCP Servers. Under Authentication, choose Flip as identity provider and select the OIDC client from step 1.
When you save the connector, Flip immediately runs the exchange for you, the logged-in administrator, and fetches the tool list from the MCP server.
⚠️ Set up the connector as a real user
The administrator who saves the connector must be a regular Flip user who resolves to an account on the MCP server side.
If the exchange fails, the connector form shows the error, including the HTTP status and the response body from Flip's identity provider. See Troubleshooting.
The access token issued by Flip
Flip signs the access token with the same key material it uses for its OIDC tokens (RS256 by default). Ask AI requests a new token at tool discovery and for every tool call, so your MCP server always receives a token for the user who is chatting.
Decoded example (values shortened, signature omitted, not every claim shown):
| Claim | Meaning |
|---|---|
iss | The Flip issuer, https://{domain}/auth/realms/{organisation-id}. |
aud | The Client ID of the OIDC client selected on the MCP connector. |
azp | flip-ask-ai, the Flip client that requested the token. |
sub | Flip's stable, opaque user ID. Identical to the sub you receive from other Flip OIDC tokens. |
email | The user's Flip email address. Be aware that not all users in an organisation necessarily have an email address, and it may not be a company address. |
preferred_username | The user's Flip username. Many organisations use the employee ID as the Flip username. |
api_access | Always false. The token cannot be used to call Flip APIs on behalf of the user. |
iat, exp | Standard JWT timestamps. |
Flip issuer
The issuer contains the domain on which the user uses Flip. Your MCP server needs to trust all domains that are used by the organisation. Testing environments have a different domain and therefore a different issuer than production.
Validating the access token on your side
Your MCP server (or MCP gateway) must validate every token before it serves a request. At minimum:
- Signature: verify against the keys published at the Flip JWKS endpoint. Resolve it via the discovery document (
jwks_uri) and cache the keys, honouring thekidheader. Keys rotate. - Issuer:
issequals the Flip issuer,https://{domain}/auth/realms/{organisation-id}for one of the domains used by the organisation. See Flip issuer. - Audience:
audcontains the Client ID of the OIDC client created in Flip. - Expiry:
expis in the future,iatis not in the future. Allow a small clock skew. - User resolution: map
sub,emailorpreferred_usernameto an account, and apply that user's permissions. Answer401or403if the user is not allowed to use the MCP server.
If your MCP server already validates tokens from your own identity provider, add Flip as a second trusted issuer with its own JWKS and audience. Do not accept Flip tokens for the audience of your own clients, and do not accept tokens from your own identity provider for the Flip audience.
Troubleshooting
- Error messages: when saving an MCP connector fails, the console shows the HTTP status and the body returned by Flip's identity provider. End users in chat only see a generic message; details are not exposed to them.
- "Could not obtain a token for the selected OIDC client": the OIDC client does not allow Ask AI. Open the OIDC client and add Ask AI under Token exchange.
- The OIDC client is not offered on the MCP connector: same cause. Only clients that allow Ask AI are listed.
- Flip cannot hand over tokens for inspection. Production systems do not log tokens or their claims. To debug claim values, log the incoming token on your MCP server in a test environment.
- Issuer mismatch: check that the MCP server trusts
https://{domain}/auth/realms/{organisation-id}for all domains that are used by the organisation. See Flip issuer. - Audience mismatch: compare the
audclaim with the Client ID of the OIDC client character by character. - The tool list cannot be fetched during setup: the administrator saving the connector has no matching identity on the MCP server side. Repeat the setup as a real user with a valid identity.
- Access works in one Flip environment but not another: the Flip issuer and the OIDC client differ per environment and per organisation, and the MCP server must accept each one.
Additional resources
- Authorization in the MCP specification
- RFC 8693: OAuth 2.0 Token Exchange
- RFC 9068: JWT Profile for OAuth 2.0 Access Tokens
- OIDC Public Client Implementation Guide for the Flip identity provider endpoints
- MCP Enterprise-Managed Authorization Guide for MCP servers behind their own authorization server
For questions or assistance, please contact your Customer Success representative.