https://github.com/clerk/toolbox
https://github.com/clerk/toolbox
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/clerk/toolbox
- Owner: clerk
- License: mit
- Created: 2025-06-27T16:55:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-27T20:28:15.000Z (about 1 year ago)
- Last Synced: 2025-06-27T20:41:43.029Z (about 1 year ago)
- Language: TypeScript
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
> [!NOTE]
> Toolbox is still in development. There will not be semver guarantees until 1.0.0.
# Toolbox
Toolbox is a production-grade library for connecting to MCP servers that require authentication.
## What makes Toolbox production-grade?
Toolbox was built with an emphasis on security and practical credential management. There are two critical differences compared to other utilities for leveraging MCP servers:
### Access and refresh tokens stay on the server
Access and refresh tokens for users are never sent to the frontend, which ensures they cannot be compromised in an XSS attack.
### Only one OAuth Client is registered per OAuth Server
When using MCP, the service provider should manage a single OAuth Server, while your agent should operate one OAuth Client.
This is preferred over implementations that dynamically register a new OAuth Client for each user, since it allows providers to understand which activity is coming from your agent.
## Installation
```bash
npm install toolbox
```
## Quick Start
### 1. Mount the handler
Create a Next.js API route at `app/toolbox/route.ts`:
```typescript
import { Toolbox } from "toolbox/nextjs/server";
import { SelfStorageAuthProvider } from "toolbox/nextjs/auth/self-storage";
import fsStore from "toolbox/storage/fs";
const toolbox = new Toolbox({
auth: new SelfStorageAuthProvider({
store: fsStore,
userId: "u_12345", // Replace with your user ID
oauthClientName: "My App",
oauthClientUri: "https://myapp.com",
discoveryOptions: {
resourceVsProtectedResourceMetadata: "any",
},
}),
store: fsStore,
});
export const { GET, POST } = toolbox.handlers();
```
### 2. Manage connections with `useToolbox()`
Use the React hook in your components:
```typescript
import { useToolbox } from "toolbox/nextjs";
export default function MyComponent() {
const { toolbox, isLoaded } = useToolbox();
const handleAddServer = async (event: React.FormEvent) => {
event.preventDefault();
const formData = new FormData(event.currentTarget);
await toolbox.addServer(formData);
};
if (!isLoaded) return
Loading...;
return (
{toolbox.servers.map((server) => (
{server.url}
Status: {server.authorization.status}
{server.authorization.status === "requires_connection" && (
{
const result = await server.generateAuthorizationUrl();
if ("authorizationUrl" in result) {
window.location.href = result.authorizationUrl;
}
}}
>
Connect
)}
))}
Add Server
);
}
```
### 3. Pass the MCP context to your AI solution
Coming soon.
## Configuration Options
### Auth Providers
Toolbox supports multiple authentication providers:
- **SelfStorageAuthProvider**: Stores OAuth credentials and tokens in your configured data store
- **ClerkAuthProvider**: Uses Clerk to manage credentials and token (coming soon)
### Data Stores
Choose from multiple storage backends:
- **File System**: `toolbox/storage/fs` (default, good for development)
- **Redis**: `toolbox/storage/redis`
- **PostgreSQL**: `toolbox/storage/postgres`
- **SQLite**: `toolbox/storage/sqlite`
### Server Status
MCP servers can have the following authorization statuses:
- `not_required`: Server doesn't require authentication
- `discovery_failed`: Failed to discover OAuth configuration
- `requires_registration`: Client registration needed
- `requires_connection`: User needs to authorize
- `connected`: Fully authenticated and ready to use
## API Reference
### useToolbox(toolboxUrl?: string)
Returns an object with:
- `toolbox`: Object containing servers and methods
- `isLoaded`: Boolean indicating if data has loaded
### toolbox.servers
Array of MCP server objects with:
- `id`: Unique server identifier
- `url`: Server endpoint URL
- `authorization`: OAuth configuration and status
- `hasAccessToken`: Whether user has authorized access
- `retryDiscovery()`: Retry OAuth discovery
- `generateAuthorizationUrl()`: Generate OAuth authorization URL
### toolbox.addServer(formData: FormData)
Add a new MCP server. FormData should contain:
- `url`: The MCP server endpoint URL
## Examples
See the [nextjs-selfstorage example](./examples/nextjs-selfstorage) for a complete working implementation.
The output of toolbox is an array of connected MCP servers and the OAuth access tokens necessary to communicate with them.
We'll provide helpers to pass that data to your preferred AI solution.