> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkOS Provider

> Configure WorkOS AuthKit authentication for a TypeScript MCP server.

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](/typescript/api-reference/server/auth-providers#oauthworkosprovider) for exact `oauthWorkOSProvider()` options, defaults, and errors.

## Configure WorkOS

In the [WorkOS Dashboard](https://dashboard.workos.com/):

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

```text theme={null}
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

```bash theme={null}
MCP_USE_OAUTH_WORKOS_SUBDOMAIN=your-company.authkit.app
```

Use the full AuthKit domain as the subdomain value.

## Configure the MCP server

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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](/typescript/server/authentication/user-context) for shared access-control patterns.

## Verify the setup

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Runnable WorkOS example" icon="github" href="https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/workos">
    Compare your setup with a working mcp-use WorkOS server.
  </Card>

  <Card title="WorkOS AuthKit MCP guide" icon="book-open" href="https://workos.com/docs/authkit/mcp">
    Review WorkOS AuthKit MCP setup.
  </Card>

  <Card title="User Context" icon="user" href="/typescript/server/authentication/user-context">
    Use WorkOS identity and organization data inside tools.
  </Card>

  <Card title="WorkOS provider API reference" icon="terminal" href="/typescript/api-reference/server/auth-providers#oauthworkosprovider">
    Look up exact provider options and defaults.
  </Card>
</CardGroup>