Deploy Your Own Executor in 10 Minutes
This tutorial walks you through deploying a custom executor to Vercel and connecting it to your TPMJS collections. No coding required.
Prerequisites
Vercel Account
Free tier works great. Sign up here if you don't have one.
TPMJS Account
You'll need a collection or agent to connect your executor to. Create an account if needed.
Deploy the Executor Template
Click the button below to deploy the TPMJS executor template to your Vercel account. This creates a private copy you fully control.
What happens when you click:
- Vercel clones the executor template to your GitHub account
- A new Vercel project is created and linked to the repository
- The executor is automatically deployed to a URL like
tpmjs-executor-xxx.vercel.app - Future pushes to your repo trigger automatic redeployments
Configure Environment Variables (Optional)
After deployment, you can add environment variables for security and customization. Go to your Vercel project → Settings → Environment Variables.
# Optional: Require authentication for all requests
EXECUTOR_API_KEY=your-secret-api-key
# Optional: Custom environment variables for your tools
MY_API_KEY=sk-xxx
DATABASE_URL=postgresql://...Security Recommendation
Set EXECUTOR_API_KEY to require authentication. Without it, anyone with your executor URL can execute tools.
Verify Your Executor is Running
Once deployed, test that your executor is healthy by calling the health endpoint. Replace the URL with your actual deployment URL.
Run this command:
curl -X GET https://your-executor.vercel.app/healthExpected response:
{
"status": "ok",
"version": "1.0.0"
}If you see "status": "ok", your executor is running and ready to use!
Test Tool Execution (Optional)
Before connecting to TPMJS, you can verify tool execution works directly. This calls the hello world tool on your executor.
Test execution:
curl -X POST https://your-executor.vercel.app/execute-tool \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret-api-key" \
-d '{
"packageName": "@anthropic-ai/tpmjs-hello",
"name": "helloWorld",
"params": { "name": "World" }
}'Expected response:
{
"success": true,
"output": "Hello, World!",
"executionTimeMs": 145
}Connect to Your Collection
Now connect your executor to a TPMJS collection so all tools in that collection run on your infrastructure.
- a
Go to your Collections dashboard
- b
Click on the collection you want to use your executor with
- c
Click the "Edit" button
- d
In the "Executor Configuration" section, select "Custom Executor"
- e
Enter your executor URL (e.g.,
https://tpmjs-executor-xxx.vercel.app) - f
If you set an API key, enter it in the "API Key" field
- g
Click "Verify Connection" to test the configuration
- h
Click "Save Changes"
Pro Tip
You can also configure executors at the Agent level. Agent executor config takes priority over collection config. See executor cascade for details.
You're Done!
All tools in your collection now execute on your custom executor. When you or anyone else uses your collection via MCP, the tools run on your Vercel deployment instead of the TPMJS default executor.
Full Privacy
Tool execution happens entirely on your infrastructure. No data passes through TPMJS servers.
Custom Environment
Add your own API keys and secrets as environment variables in Vercel.
Your Limits
Execution timeouts and rate limits are controlled by your Vercel plan.
Full Control
Fork and modify the executor code to add custom functionality.
Troubleshooting
"Verification failed" when connecting
- Check that your executor URL is correct (no trailing slash)
- Ensure the executor is deployed and healthy (check
/healthendpoint) - If using an API key, make sure it matches what's in Vercel environment variables
Tools timing out
- Vercel's free tier has a 10-second timeout per request
- Upgrade to Pro for 60-second timeouts, or use a different host
- Consider caching or optimizing slow tools
"Unauthorized" errors
- Your executor has
EXECUTOR_API_KEYset but you didn't provide it in TPMJS - Go to your collection/agent settings and add the API key