WorkOS Provider

Use the WorkOS provider when WorkOS AuthKit is your identity layer. MCP clients authenticate with WorkOS, and your MCP server verifies WorkOS-issued tokens. This guide covers the WorkOS setup path. Use the auth providers API reference for exact oauthWorkOSProvider() options, defaults, and errors.

Configure WorkOS

In the WorkOS Dashboard:

Create or open a project.
Go to Connect > Configuration.
Enable Dynamic Client Registration.
Enable Client ID Metadata Document if your MCP clients support it.
Add your MCP server URL as a Resource Indicator.

http://localhost:3000

The default mcp-use authorization challenge points clients to protected-resource metadata whose resource value is the server base URL. Add a path-specific resource indicator such as http://localhost:3000/mcp only when your clients request that scoped resource value.

Set environment variables

MCP_USE_OAUTH_WORKOS_SUBDOMAIN=your-company.authkit.app

Use the full AuthKit domain as the subdomain value.

Configure the MCP server

import { MCPServer } from "mcp-use";
import { oauthWorkOSProvider } from "mcp-use/oauth/workos";

const server = new MCPServer({
  name: "workos-server",
  version: "1.0.0",
  oauth: oauthWorkOSProvider(),
});

await server.listen(3000);

You can pass the AuthKit domain directly instead of using an environment variable:

oauth: oauthWorkOSProvider({
  subdomain: "your-company.authkit.app",
});

If your tools call the WorkOS Management API, store that API key separately. It is not part of the OAuth provider config.

Scope data by organization

WorkOS can include organization context in the token. Use it to filter tenant-specific data.

import { error, object } from "mcp-use";

server.tool(
  {
    name: "list_documents",
    description: "List documents for the authenticated WorkOS organization.",
  },
  async (_args, ctx) => {
    if (!ctx.auth) {
      return error("Unauthorized");
    }

    const organizationId = ctx.auth.user.organization_id as string | undefined;

    if (!organizationId) {
      return error("Organization context required.");
    }

    const documents = await db.documents.findMany({
      where: { organizationId },
    });

    return object({ documents });
  },
);

Use User Context for shared access-control patterns.

Verify the setup

Run the server and connect with an OAuth-capable MCP client.

npm run dev

Confirm these cases:

The client discovers WorkOS OAuth metadata.
The client signs in through WorkOS.
WorkOS issues an access token whose audience matches the MCP resource indicator.
Authenticated tool calls include ctx.auth.user.userId.
Organization-scoped tools reject calls without organization context.

Next steps

Runnable WorkOS example

Compare your setup with a working mcp-use WorkOS server.

WorkOS AuthKit MCP guide

Review WorkOS AuthKit MCP setup.

User Context

Use WorkOS identity and organization data inside tools.

WorkOS provider API reference

Look up exact provider options and defaults.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

WorkOS Provider

Configure WorkOS

Set environment variables

Configure the MCP server

Scope data by organization

Verify the setup

Next steps

Runnable WorkOS example

WorkOS AuthKit MCP guide

User Context

WorkOS provider API reference

​Configure WorkOS

​Set environment variables

​Configure the MCP server

​Scope data by organization

​Verify the setup

​Next steps

Runnable WorkOS example

WorkOS AuthKit MCP guide

User Context

WorkOS provider API reference

Configure WorkOS

Set environment variables

Configure the MCP server

Scope data by organization

Verify the setup

Next steps