Clerk MCP Server

Official Clerk toolkit that exposes user, organization, session, and invitation management APIs as MCP tools for AI agents.

Developer Tools by Clerk API Key active

GitHub Docs npm: @clerk/agent-toolkit

Overview

@clerk/agent-toolkit is Clerk's official integration package for AI agent frameworks. It exposes a curated subset of Clerk's Backend Management API as callable tools, letting agents create and update users, manage organizations and memberships, send invitations, and read session context. The package ships three entry points: @clerk/agent-toolkit/ai-sdk for Vercel's AI SDK, @clerk/agent-toolkit/langchain for LangChain, and @clerk/agent-toolkit/modelcontextprotocol for the Model Context Protocol.

The MCP integration runs as a local stdio server launched via npx, authenticated with a Clerk secret key. Tool exposure can be scoped using the --tools flag, accepting category names (users, organizations), wildcards (users.*), or specific tool names (users.getUserCount). This lets you give an agent only the permissions it actually needs.

Note: This is distinct from Clerk's other hosted MCP server at https://mcp.clerk.com/mcp, which serves Clerk SDK code snippets to AI coding assistants rather than managing live Clerk resources. The agent-toolkit is the one you want when you need an agent to actually read or mutate users, organizations, and invitations in your Clerk instance. The package is marked experimental by Clerk.

Tools

Tool	Description
`users.getUserId`	Returns the current authenticated user's ID, or null when no session is present.
`users.getUser`	Fetches a user record including email addresses, username, profile image, and timestamps.
`users.getUserCount`	Returns the total number of users in the Clerk instance.
`users.updateUser`	Updates user attributes such as first name, last name, username, or profile image URL.
`users.updateUserPublicMetadata`	Deep-merges values into a user's public metadata (readable from frontend and backend).
`users.updateUserUnsafeMetadata`	Deep-merges values into a user's unsafe metadata (writable from frontend).
`organizations.getOrganization`	Retrieves an organization by ID or slug.
`organizations.createOrganization`	Creates a new organization with an optional metadata payload.
`organizations.updateOrganization`	Updates an organization's attributes such as name or slug.
`organizations.updateOrganizationMetadata`	Deep-merges values into an organization's public or private metadata.
`organizations.deleteOrganization`	Permanently deletes an organization. Irreversible.
`organizations.createOrganizationMembership`	Adds a user to an organization with a specified role.
`organizations.updateOrganizationMembership`	Changes a user's role within an organization.
`organizations.updateOrganizationMembershipMetadata`	Deep-merges metadata onto an organization membership.
`organizations.deleteOrganizationMembership`	Removes a user from an organization.
`organizations.createOrganizationInvitation`	Invites an email address to join an organization with a given role.
`organizations.revokeOrganizationInvitation`	Cancels a pending organization invitation.
`invitations.createInvitation`	Creates an application-wide signup invitation for an email address.
`invitations.revokeInvitation`	Revokes a pending application-wide invitation.

Setup Guide

Prerequisites

A Clerk account with an application created at dashboard.clerk.com
Your Clerk Secret Key (starts with sk_test_ or sk_live_)
Node.js installed locally (the server runs via npx)

Claude Desktop / Cursor config

Add this to your MCP client config (e.g. claude_desktop_config.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "clerk": {
      "command": "npx",
      "args": [
        "-y",
        "@clerk/agent-toolkit",
        "-p=local-mcp",
        "--secret-key=sk_test_xxx"
      ]
    }
  }
}

Replace sk_test_xxx with your actual Clerk secret key. You can also pass the key via the CLERK_SECRET_KEY environment variable instead of the --secret-key flag.

Scoping available tools

Use the --tools flag to limit what the agent can call:

--tools=users exposes only user tools
--tools="users.*" is equivalent (all user tools via wildcard)
--tools users organizations exposes multiple categories
--tools users.getUserCount organizations.getOrganization exposes specific tools only

Example restricting to read-only user counts:

{
  "mcpServers": {
    "clerk": {
      "command": "npx",
      "args": [
        "-y",
        "@clerk/agent-toolkit",
        "-p=local-mcp",
        "--tools=users.getUserCount",
        "--secret-key=sk_test_xxx"
      ]
    }
  }
}

Security note

The secret key grants full backend access to your Clerk instance. Treat the config file like any other secret store, and prefer narrow --tools scopes over exposing everything.

Use Cases

Provision new users and seed their public metadata from an onboarding agent that collects profile data over chat.
Let a support agent look up a user by ID, check organization membership, and update their role without leaving the conversation.
Automate organization setup: create the org, invite the founding team by email, and assign roles in one agent turn.
Run scheduled analytics prompts that pull users.getUserCount and organization stats into a daily summary.
Build internal tooling where ops staff ask an agent to revoke a stale invitation or off-board a user from an org.

Example Prompts

"Create a new organization called Acme Corp owned by user_2abc and invite founders@acme.com as admin."
"How many users do we have in total, and how many signed up in organizations vs. as solo accounts?"
"Find user user_xyz, update their public metadata with plan: pro, and confirm the change."
"Revoke the pending invitation to contractor@example.com on the Acme Corp organization."
"Promote user user_123 to admin in organization org_456."

Pros

Maintained by Clerk inside the official clerk/javascript monorepo, so it tracks the Backend API directly.
Fine-grained tool scoping via --tools lets you expose only the operations an agent needs.
Single package covers Vercel AI SDK, LangChain, and MCP, so the same tool surface works across frameworks.
Handles user, organization, membership, and invitation flows that are central to most SaaS auth backends.

Limitations

Marked experimental by Clerk, so APIs and tool names can change.
Authenticates with a long-lived Clerk Secret Key; there is no per-user OAuth scoping for the MCP transport itself.
Tool surface is a subset of Clerk's full Backend API; not every endpoint (e.g. JWT templates, webhooks) is exposed.

Alternatives

Clerk MCP Server (hosted): different product from the same vendor that serves SDK code snippets, useful for AI coding assistants but not for managing live Clerk data.
Auth0 MCP Server: equivalent capability for Auth0 tenants.
Supabase MCP Server: if you use Supabase Auth instead of Clerk, this exposes auth and database operations as tools.