[!IMPORTANT]Agent behavior is typically non-deterministic. Ensure you thoroughly test your integration and evaluate your application's performance. Additionally, consider scoping this toolkit's tools to specific users to limit resource access.If your app's code path is predetermined, it's always preferable to call APIs directly instead of using agents and tool calling.This SDK is recommended for testing purposes only unless you are confident in the agent's behavior and have implemented necessary security measures such as guardrails and best practices.
Table of Contents
- Table of Contents
- Getting Started
- API Reference
- Prerequisites
- Example Repository
- Using Vercel's AI SDK
- Using Langchain
- Model Context Protocol (MCP Server)
- Advanced Usage
- Support
- Contributing
- License
Getting Started
Use this SDK to integrate Clerk into your agentic workflows. The Clerk Agent Toolkit enables popular agent frameworks, including Vercel's AI SDK and LangChain, to integrate with Clerk using tools (also known as function calling).
This package exposes a subset of Clerk's functionality to agent frameworks, allowing you to build powerful agentic systems capable of managing users, user data, organizations, and more.
API Reference
Import Paths
The Clerk Agent Toolkit package provides two main import paths:
@clerk/agent-toolkit/ai-sdk: Helpers for integrating with Vercel's AI SDK.
@clerk/agent-toolkit/langchain: Helpers for integrating with Langchain.
@clerk/agent-toolkit/modelcontextprotocol: Low level helpers for integrating with the Model Context Protocol (MCP).
The toolkit offers the same tools and core APIs across frameworks, but their public interfaces may vary slightly to align with each framework's design:
Methods
Initialization & generic helpers
createClerkToolkit(options): Instantiates a new Clerk toolkit.
toolkit.injectSessionClaims(systemPrompt): Injects session claims (userId,sessionId,orgId, etc.) into the system prompt, making them accessible to the AI model.
Available tools
Currently, are only exposing a subset of Clerk Backend API functionality as tools. We plan to expand this list as we receive feedback from the community. You are welcome to open an issue or reach out to us on Discord to request additional tools.
toolkit.users(): Provides tools for managing users. Details.
toolkit.organizations(): Provides tools for managing organizations. Details.
toolkit.invitations(): Provides tools for managing invitations. Details.
toolkit.allTools(): Returns all available tools.
Langchain-specific methods
toolkit.toolMap(): Returns an object mapping available tools, useful for calling tools by name.
MCP Specific Methods
createClerkMcpServer(): Instantiates a new Clerk MCP server. For more details, see
For more details on each tool, refer to the framework-specific directories or the Clerk Backend API documentation.
Prerequisites
ai-sdk:"^3.4.7 || ^4.0.0", orlangchain:"^0.3.6"
- An existing Clerk application. Create your account for free.
- An API key for an AI model compatible with Langchain
Example Repository
Using Vercel's AI SDK
- Install the Clerk Agent Toolkit package:
- Set the Clerk secret key as an environment variable in your project. Ensure you also configure any required LLM model keys.
- Import the helper from the
/ai-sdkpath, instantiate a new Clerktoolkit, and use it in your agent function:
Using Langchain
- Install the Clerk Agent Toolkit package:
- Set the Clerk secret key as an environment variable:
- Import the helper from the
/langchainpath, instantiate a new Clerktoolkit, and use it in your agent function:
Model Context Protocol (MCP Server)
The
@clerk/agent-toolkit/modelcontextprotocol import path provides a low-level helper for integrating with the Model Context Protocol (MCP). This is considered an advanced use case, as most users will be interested in running a local Clerk MCP server directly instead.Running a local MCP server
To run the Clerk MCP server locally using
npx, run the following command:By default, the MCP server will use all available Clerk tools as described in the Available tools: section. To limit the tools available to the server, use the
--tools (-t) flag:Use the
--help flag to view additional server options.Usage with Claude Desktop
Add the following to your
claude_desktop_config.json file to use the local MCP server:For more information, please refer to the Claude Desktop documentation.
Advanced Usage
Using a Custom `clerkClient`
If you need to set the Clerk secret key dynamically or use different Clerk instances, pass a custom
clerkClient. Install @clerk/backend into your project and call the createClerkClient function:Support
You can get in touch with us in any of the following ways:
- Join our official community Discord server
Contributing
We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.
License
This project is licensed under the MIT license.
See LICENSE for more information.
[!IMPORTANT]Agent behavior is typically non-deterministic. Ensure you thoroughly test your integration and evaluate your application's performance. Additionally, consider scoping this toolkit's tools to specific users to limit resource access.If your app's code path is predetermined, it's always preferable to call APIs directly instead of using agents and tool calling.This SDK is recommended for testing purposes only unless you are confident in the agent's behavior and have implemented necessary security measures such as guardrails and best practices.
Table of Contents
- Table of Contents
- Getting Started
- API Reference
- Prerequisites
- Example Repository
- Using Vercel's AI SDK
- Using Langchain
- Model Context Protocol (MCP Server)
- Advanced Usage
- Support
- Contributing
- License
Getting Started
Use this SDK to integrate Clerk into your agentic workflows. The Clerk Agent Toolkit enables popular agent frameworks, including Vercel's AI SDK and LangChain, to integrate with Clerk using tools (also known as function calling).
This package exposes a subset of Clerk's functionality to agent frameworks, allowing you to build powerful agentic systems capable of managing users, user data, organizations, and more.
API Reference
Import Paths
The Clerk Agent Toolkit package provides two main import paths:
@clerk/agent-toolkit/ai-sdk: Helpers for integrating with Vercel's AI SDK.
@clerk/agent-toolkit/langchain: Helpers for integrating with Langchain.
@clerk/agent-toolkit/modelcontextprotocol: Low level helpers for integrating with the Model Context Protocol (MCP).
The toolkit offers the same tools and core APIs across frameworks, but their public interfaces may vary slightly to align with each framework's design:
Methods
Initialization & generic helpers
createClerkToolkit(options): Instantiates a new Clerk toolkit.
toolkit.injectSessionClaims(systemPrompt): Injects session claims (userId,sessionId,orgId, etc.) into the system prompt, making them accessible to the AI model.
Available tools
Currently, are only exposing a subset of Clerk Backend API functionality as tools. We plan to expand this list as we receive feedback from the community. You are welcome to open an issue or reach out to us on Discord to request additional tools.
toolkit.users(): Provides tools for managing users. Details.
toolkit.organizations(): Provides tools for managing organizations. Details.
toolkit.invitations(): Provides tools for managing invitations. Details.
toolkit.allTools(): Returns all available tools.
Langchain-specific methods
toolkit.toolMap(): Returns an object mapping available tools, useful for calling tools by name.
MCP Specific Methods
createClerkMcpServer(): Instantiates a new Clerk MCP server. For more details, see
For more details on each tool, refer to the framework-specific directories or the Clerk Backend API documentation.
Prerequisites
ai-sdk:"^3.4.7 || ^4.0.0", orlangchain:"^0.3.6"
- An existing Clerk application. Create your account for free.
- An API key for an AI model compatible with Langchain
Example Repository
Using Vercel's AI SDK
- Install the Clerk Agent Toolkit package:
- Set the Clerk secret key as an environment variable in your project. Ensure you also configure any required LLM model keys.
- Import the helper from the
/ai-sdkpath, instantiate a new Clerktoolkit, and use it in your agent function:
Using Langchain
- Install the Clerk Agent Toolkit package:
- Set the Clerk secret key as an environment variable:
- Import the helper from the
/langchainpath, instantiate a new Clerktoolkit, and use it in your agent function:
Model Context Protocol (MCP Server)
The
@clerk/agent-toolkit/modelcontextprotocol import path provides a low-level helper for integrating with the Model Context Protocol (MCP). This is considered an advanced use case, as most users will be interested in running a local Clerk MCP server directly instead.Running a local MCP server
To run the Clerk MCP server locally using
npx, run the following command:By default, the MCP server will use all available Clerk tools as described in the Available tools: section. To limit the tools available to the server, use the
--tools (-t) flag:Use the
--help flag to view additional server options.Usage with Claude Desktop
Add the following to your
claude_desktop_config.json file to use the local MCP server:For more information, please refer to the Claude Desktop documentation.
Advanced Usage
Using a Custom `clerkClient`
If you need to set the Clerk secret key dynamically or use different Clerk instances, pass a custom
clerkClient. Install @clerk/backend into your project and call the createClerkClient function:Support
You can get in touch with us in any of the following ways:
- Join our official community Discord server
Contributing
We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.
License
This project is licensed under the MIT license.
See LICENSE for more information.