> ## 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.

# Clerk Provider

> Configure Clerk OAuth authentication for a TypeScript MCP server.

Use the Clerk provider when Clerk is your identity system. MCP clients register directly with Clerk through Dynamic Client Registration, and your MCP server verifies Clerk-issued tokens.

This guide covers the Clerk setup path. Use the [auth providers API reference](/typescript/api-reference/server/auth-providers#oauthclerkprovider) for exact `oauthClerkProvider()` options, defaults, and errors.

## Configure Clerk

In the [Clerk Dashboard](https://dashboard.clerk.com/):

1. Create or open your Clerk application.
2. Go to **Configure > OAuth Applications**.
3. Enable **Dynamic Client Registration**.
4. Enable the `user:org:read` scope if your tools need Clerk organization context.
5. Go to **API Keys** and copy your Frontend API URL.

The Frontend API URL usually looks like one of these:

```text theme={null}
https://verb-noun-42.clerk.accounts.dev
https://clerk.your-domain.com
```

## Set environment variables

```bash theme={null}
MCP_USE_OAUTH_CLERK_FRONTEND_API_URL=https://verb-noun-42.clerk.accounts.dev
```

## Configure the MCP server

```typescript theme={null}
import { MCPServer } from "mcp-use";
import { oauthClerkProvider } from "mcp-use/oauth/clerk";

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

await server.listen(3000);
```

You can pass the Frontend API URL directly instead of using an environment variable:

```typescript theme={null}
oauth: oauthClerkProvider({
  frontendApiUrl: "https://verb-noun-42.clerk.accounts.dev",
});
```

If your tools need Clerk organization context, advertise the organization scope too:

```typescript theme={null}
oauth: oauthClerkProvider({
  frontendApiUrl: "https://verb-noun-42.clerk.accounts.dev",
  scopesSupported: ["profile", "email", "offline_access", "user:org:read"],
});
```

## Use organization claims

When you use Clerk Organizations, Clerk can include `org_id` in the token. This requires Organizations to be enabled, the `user:org:read` scope to be available to the OAuth app, and the client to request that scope.

```typescript theme={null}
import { error, object } from "mcp-use";

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

    const orgId = ctx.auth.user.org_id as string | undefined;

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

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

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

The SDK preserves `org_role` and `org_slug` on `ctx.auth.user`. When Clerk includes `org_permissions`, the SDK maps them to `ctx.auth.user.permissions`. Treat these fields as optional and guard before using them.

## 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 Clerk OAuth metadata.
* The client registers with Clerk.
* Authenticated tool calls include `ctx.auth.user.userId`.
* Organization-scoped tools are tested with a client that requested `user:org:read`.
* Organization-scoped tools reject calls without organization context.

## Next steps

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

  <Card title="Clerk OAuth documentation" icon="book-open" href="https://clerk.com/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth">
    Review Clerk's OAuth behavior.
  </Card>

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

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