Skip to main content
Directory Sync connects a FastMCP Gateway organization to an identity provider through WorkOS. The identity provider remains the source of directory users and group membership, while WorkOS carries lifecycle changes into FastMCP Gateway organization membership.
Directory Sync is available on Enterprise. You must be an organization Admin to configure it. You also need permission to configure applications in your identity provider. If the Directory Sync card is not visible, open the organization’s Billing view to confirm its current plan.

​
Provisioning model

Directory Sync separates identity configuration from FastMCP Gateway access management. Your identity provider decides which people and groups belong in the directory. WorkOS hosts the provider-specific SCIM connection and sends user and membership changes to FastMCP Gateway. FastMCP Gateway reflects the WorkOS organization membership and shows the connection state. Directory groups and their membership synchronize into directory-backed FastMCP Gateway Teams. A group member can appear as pending until WorkOS has also provisioned that person’s FastMCP Gateway account. Review these groups and their members under Organization settings > Teams.

​
Connect directory

FastMCP Gateway generates the setup link, while the identity provider connection is configured in the WorkOS Admin Portal. Each setup action creates a one-time portal link. Open it immediately and complete the task in that browser tab.
1

Open Directory Sync

Select the gear next to your organization name in the FastMCP Gateway header, then select Single Sign-on. The Directory Sync card appears below the SSO settings.
2

Open WorkOS

Select Configure directory sync. FastMCP Gateway generates a one-time link and opens the WorkOS Admin Portal in a new tab.
3

Configure the provider

Choose your identity provider and follow its instructions in the linked portal. The portal supplies the SCIM values and configuration steps for Okta, Microsoft Entra ID, and other supported providers.
4

Activate the directory

Complete the connection validation in WorkOS. Return to FastMCP Gateway and reload the page if needed. The Directory Sync card shows Connected when WorkOS reports that the directory is connected.

​
Verify provisioning

Test the connection with a person whose membership you can safely change in the identity provider.
1

Provision a person

Assign the person to the application for FastMCP Gateway in your identity provider using the provider’s normal provisioning workflow.
2

Check directory counts

Return to the Directory Sync card. Its Members, Active, and Inactive values are live counts from the WorkOS directory. Reload the page if the new directory user has not appeared yet.
3

Complete first sign-in

Ask the person to sign in to FastMCP Gateway with their work email address. WorkOS activates the pending organization membership during the first sign-in. FastMCP Gateway grants organization access only after that membership is active.
4

Confirm membership

Open Organization settings > Members and confirm that the person belongs to the organization. Open the corresponding directory-backed Team to verify its group membership.
The card’s Connected time records when the directory connection was created. It is not the time of the latest successful synchronization.

​
Roles and access

Connecting a directory provisions organization membership. It does not by itself grant access to a server. WorkOS IdP Role Assignment can map identity provider groups to the FastMCP Gateway organization roles Admin, Member, and Resource User. That organization-role configuration lives in WorkOS and is separate from the Directory Sync connection. Server roles are assigned separately in FastMCP Gateway. Explicit server grants and server default roles remain available for provisioned members. Directory groups also become Teams, and Team grants are enforced on eligible plans. Directory Sync never creates, changes, or removes those grants. Admins manage Team grants from a server’s Access > Members page and review a Team’s saved grants from its Servers tab. See Roles for how organization roles, explicit grants, team grants, and server default roles combine.

​
Deprovisioning

Deprovision a person through the identity provider so that WorkOS remains the source of their lifecycle. When FastMCP Gateway receives an inactive or deleted organization membership from WorkOS, it removes the person’s organization membership and their explicit server grants in that organization. Their personal API keys no longer provide access to that organization, although the keys are not globally revoked. If the same person is provisioned again later, prior explicit server grants are not restored automatically. Assign any required server access again after confirming the new membership on the Members page.
In Okta, suspending a person does not deprovision them through SCIM. Deactivate or delete the directory user instead, then verify the inactive directory count and FastMCP Gateway membership removal.
A temporary disconnection freezes provisioning until the directory is reconnected.
Deleting a directory marks its directory-backed Teams as missing and removes their memberships. Existing team grants remain saved, but they stop granting server access because those Teams no longer have members.
Use the provider’s deprovisioning action while the connection is active rather than disconnecting or deleting the directory to remove an individual member.

​
Connection states

FastMCP Gateway reads directory state and provider metadata from WorkOS whenever the settings page loads. For a connected directory, select Manage to generate a new one-time WorkOS portal link. Use it to review or update the provider configuration.