Skip to main content
This is a one-time setup performed once for your organization. Once complete, everyone at your company can connect their MCP clients through your corporate sign-in — no API keys to manage, and nothing for individual users to configure beyond a URL. Prophia supports any standards-compliant OIDC identity provider: Okta, Azure AD / Entra ID, Auth0, Google Workspace, Keycloak, and others.

Who does what

The setup spans two admin consoles, and in most organizations two different people. Expect to pass values back and forth between them.
“Admin” here means an administrator at your organization, not a Prophia employee. Prophia Support can complete the registration for you if you’d rather not do it yourself — see If you get stuck.

Before you start

  • Admin access on your Prophia account. The setup lives on the API/MCP Config tab in Account Settings, which appears only for account admins on accounts with API access enabled. If you don’t see the tab, contact Prophia Support to confirm API access is enabled.
  • Admin access to your identity provider, so you can create an OIDC application.
Setup is per Prophia account. If your company has more than one Prophia account, repeat these steps for each — every account has its own API Name and its own redirect URL.

How the connection flow works

Once setup is complete, this is what happens when a user connects an MCP client — no client IDs or secrets ever reach the user: The user experiences steps 1–9 as a single browser prompt: they sign in with their work account and, on accounts that use role-based permissions, go through the consent screen (step 8). Every OAuth client gets the consent screen, whichever one the user connects. There the user chooses which Prophia capabilities the client gets, and every tool call on that connection is limited to them. A client with a refresh token keeps that choice when it refreshes. A client without one repeats steps 5–9 when its access token expires after 12 hours, consent screen included, and so does any client once the connection reaches its maximum lifetime. See Choosing what a connection can access and How long a connection lasts.

How long a connection lasts

  • Access tokens last 12 hours. A client that registered without a client secret signs the user in again when its access token expires.
  • A client that registered with a client secret also gets a refresh token, which it uses to get new access tokens without the user signing in again. Each refresh token lasts 30 days and is replaced every time it’s used, so a connection left unused for 30 days ends.
  • Every connection ends at your account’s maximum connection lifetime, counted from the user’s sign-in, however actively it’s used. The client can’t refresh past that point, but the access token it already has keeps working until it expires, so a connection can last up to 12 hours longer. After it ends, the user signs in again through your IdP. The lifetime defaults to 30 days. To change it, enter any number of days from 1 to 180 in the Maximum connection lifetime (days) field on the OAuth client for MCP card (Account Settings → API/MCP Config → Authorization Options → MCP OAuth).

Step 1 — Copy your redirect URL from Prophia

Start in Prophia, not in your IdP — you need the redirect URL before you can create the OIDC application.
1

Open the API/MCP Config tab

In Prophia, go to Account Settings and open the API/MCP Config tab.
2

Select MCP OAuth

Scroll to the Authorization Options card and select the MCP OAuth segment.
3

Copy the redirect URL

In the OAuth client for MCP card, find Redirect URL and click Copy.
The value is specific to your account and looks like this:
Copy it from the app rather than typing it. Note the host: the customer-facing MCP URL uses api.prophia.com, but the redirect URL uses yosemite-api.prophia.com. Registering the wrong host is the most common configuration mistake, and it fails silently until a user tries to log in.

Step 2 — Create an OIDC application in your IdP

In your identity provider’s admin console, create a new OIDC / OAuth2 application for Prophia: The application you create represents Prophia — not Claude, not Cursor. You create one no matter how many users or clients you have.
On some identity providers — Okta custom authorization servers in particular — the email claim has to be added to the ID token explicitly rather than relying on the email scope.

Client secret or PKCE?

Prophia supports both. Your IdP registration must match the Public client (PKCE) — no client secret checkbox you set in Prophia in Step 3; if the two disagree, login fails. A confidential client with a client secret is the recommended setup, and the more widely supported of the two. Prophia’s server is what talks to your IdP, so it can hold a secret safely. Register the app as a confidential / web application, copy the client secret your IdP generates, and leave the PKCE box unchecked in Prophia. Use a public client with PKCE if your IdP won’t issue a secret for the app type you need, or your security policy prohibits sharing a client secret with a third party. PKCE (Proof Key for Code Exchange) replaces the stored secret with a one-time challenge generated per login, so there is no shared credential to distribute or rotate. Register the app as a public client with PKCE required, and check the PKCE box in Prophia. If your IdP showed you a client secret to copy, you have a confidential client — public clients don’t get one. You can switch later by changing the registration in your IdP and updating the matching setting in Prophia.

Assign your users to the application

Most identity providers won’t let anyone sign in to an application they haven’t been assigned to. In Okta this is the Assignments tab; in Entra ID it’s Users and groups under Enterprise applications, and if the app’s Assignment required? setting is Yes, unassigned users are refused at the Microsoft sign-in screen. Assign every user or group who should be able to reach Prophia from an AI assistant.
Skipping this produces a login that fails immediately after the IdP screen appears, and it is the most common cause of a setup that looks correct but doesn’t work.

Email matching is required

The email claim returned by your IdP must exactly match the email on an existing Prophia user account. Prophia does not create users on the fly — a user who doesn’t already exist in Prophia is rejected with access denied, however successfully they signed in.

Microsoft Entra ID (Azure AD)

Here are some typical pitfalls and suggested settings when creating an Entra ID app registration for connecting to Prophia’s MCP server.
1

Register the app on the Web platform

In App registrations → your app → Authentication, add the Prophia redirect URL under the Web platform.
Do not use “Single-page application.” Entra treats a redirect URI on that platform as a public client and won’t let Prophia’s server complete the sign-in, with or without a client secret.
  • Leave Allow public client flows set to Disabled.
  • Leave the implicit-grant checkboxes (Access tokens, ID tokens) unchecked.
2

Create a client secret and copy its Value

In Certificates & secrets → New client secret, copy the Value column, not Secret ID.
  • Entra shows the value only once, right after you create it. If you didn’t copy it then, create a new secret.
  • A secret value is about 40 characters and contains Q~ near the start, for example abc8Q~…. If what you have is a GUID, it’s the Secret ID. If it has no ~, part of it was lost when copying.
  • Note the expiry date. When the secret expires, logins stop working until you create a new one and save it in Prophia.
3

Find your issuer URL and client ID

  • Issuer URL: https://login.microsoftonline.com/{Directory (tenant) ID}/v2.0, using your tenant ID from the app’s Overview page. Don’t use common or organizations.
  • Client ID: the Application (client) ID on the app’s Overview page.
This is a confidential client, so leave the PKCE box unchecked when you enter these values in Step 3.
4

Make sure each user's primary email matches Prophia

Entra fills the email claim from the user’s primary email address (the mail attribute), which is not always the sign-in name (UPN).
  • The primary email must exactly match the email on the user’s Prophia account.
  • Aliases don’t count. Secondary addresses and proxy addresses aren’t sent in the token, so an alias that matches Prophia won’t help.
  • If a user signs in successfully at Microsoft but then gets access denied, this mismatch is almost always the reason. Change the user’s primary email in Entra or the email in Prophia so they match.

Collect these values

When you’re done, take these from your IdP to Step 3:
Confirm the issuer URL before you move on. Many IdPs expose more than one. Okta uses https://your-org.okta.com for the org authorization server and https://your-org.okta.com/oauth2/default for the default custom one, and only one is right for your application. Open {issuer-url}/.well-known/openid-configuration in a browser and check that the issuer value in the response matches exactly what you’re about to paste into Prophia.

Step 3 — Register the application with Prophia

Return to the OAuth client for MCP card — Account Settings → API/MCP Config → Authorization Options → MCP OAuth — and fill in the form: Click Create. On success you’ll see a confirmation that the OAuth client configuration was saved, and the Remove button appears alongside Save changes.
The PKCE checkbox must match how you registered the application in your IdP. A confidential client with the box checked, or a public client with it unchecked, fails at login. If your IdP showed you a client secret to copy, you have a confidential client — leave the box unchecked.
The Create button stays greyed out until the issuer URL and client ID are both filled in, the issuer URL starts with http:// or https://, and either a client secret is entered or the PKCE box is checked. When you return later to edit an existing configuration, the secret already stored also satisfies that last condition, so Save changes stays available without re-typing it. Prefer not to do this yourself? Send the three values from Step 2 to your Prophia contact or Prophia Support and they’ll complete the registration for you.

Step 4 — Verify

There is no test button, and a successful save means the details were stored, not that they’re correct. Verify end to end. Ask a Prophia user at your organization — yourself, if you have an account — to connect an MCP client to https://api.prophia.com/mcp/v1/{your-api-name} following Connect Claude or Connect other clients. They should be redirected to your IdP’s login page. After signing in, and choosing what the client can access if your account uses role-based permissions, they should be able to use Prophia tools from their assistant. If login fails, work through Troubleshooting in order.

Changing or removing the configuration later

Return to the same card:
  • Update a value — edit the field and click Save changes.
  • Rotate the client secret — create the new secret in your IdP first, paste it in, and click Save changes. Leaving the field blank keeps the secret currently stored, so you can change other fields without re-entering it. Remove the old secret from your IdP once you’ve verified the new one works.
  • Turn the connection off — uncheck Enabled and click Save changes. Your details are kept, so you can switch it back on later.
  • Delete the configuration — click Remove and confirm. This deletes the stored OIDC details entirely; you’d need to re-enter them to restore OAuth access. API key connections are unaffected.
Turning the connection off, removing it, or changing the issuer URL or client ID ends existing connections. Users who are already connected keep working until their current access token expires, at most 12 hours, and then have to sign in again. A new maximum connection lifetime also applies to existing connections, so lowering it ends any connection already older than the new limit in the same way. Rotating the client secret or editing other settings doesn’t affect them.

Troubleshooting

OAuth login opens but fails

Check these in order — the first two account for most failures:
1

Are your users assigned to the OIDC application in your IdP?

An unassigned user fails right after the IdP login screen. This is the most common cause.
2

Does the redirect URI in your IdP exactly match the Redirect URL on the card?

Including the yosemite-api.prophia.com host. Copy it again from Prophia and compare character for character.
3

Is the issuer URL right?

Fetch {issuer-url}/.well-known/openid-configuration and confirm the issuer in the response matches what you entered.
4

Does your IdP registration match the PKCE checkbox?

A confidential client with the box checked, or a public client with it unchecked, will fail.
5

Is Enabled checked and saved?

On the OAuth client for MCP card.
6

Does the ID token include an email claim that matches a Prophia user?

Your IdP’s system log will usually show the claims it issued.

If you use Microsoft Entra ID

Also check these, in order:
1

Is the redirect URI on the Web platform?

Not Single-page application. Entra won’t let Prophia’s server complete the sign-in from a redirect URI registered there.
2

Is Allow public client flows disabled?

In App registrations → your app → Authentication.
3

Is the client secret in Prophia the secret's Value, and is it still valid?

Not the Secret ID. Check the expiry date in Certificates & secrets.
4

Does the user's primary email in Entra exactly match their Prophia email?

Entra sends the primary email (the mail attribute), not the sign-in name or any alias.

Other problems

The tab appears only if you’re an admin on the Prophia account you’re currently viewing, and that account has API access enabled. If you have access to more than one account, check you’re focused on the right one. If you’re an admin and still don’t see it, contact Prophia Support to confirm API access is enabled.
Your account doesn’t have one configured yet, and the connection URL shown alongside it will not work. Contact Prophia Support to have one set before continuing.
It must start with http:// or https://. A bare hostname like acme.okta.com is rejected.
The email your IdP returns doesn’t match that user’s Prophia email, or they don’t have a Prophia user account at all. Prophia won’t create one for them.

If you get stuck

If you can’t reach the API/MCP Config tab, or setup fails and none of the above helps, contact your Prophia contact or Prophia Support and we’ll configure it for you.