TPMJS Platform Guide

Account Features

• Collections - Create up to 50 collections to organize tools
• Agents - Create up to 20 AI agents with custom configurations
• API Keys - Generate up to 10 API keys for programmatic access
• Provider Keys - Store encrypted API keys for LLM providers (OpenAI, Anthropic, etc.)
• Activity Feed - Track your actions with a complete audit trail
• Usage Analytics - Monitor API calls, tokens, and costs

Username Requirements

• 3-30 characters long
• Lowercase letters, numbers, and hyphens only
• Must start and end with a letter or number (not hyphen)
• Must be unique across all TPMJS users

Valid usernames:
- ajax
- john-doe
- dev123
- my-cool-name

Invalid usernames:
- -invalid (starts with hyphen)
- also-invalid- (ends with hyphen)
- Hi (uppercase not allowed)
- ab (too short, minimum 3 chars)

Reserved Names

Certain names are reserved and cannot be used as usernames:

Checking Availability

When setting up your profile, usernames are checked in real-time for availability. You can also check programmatically:

curl https://tpmjs.com/api/user/username/check?username=your-username

Profile URL

Public vs Private

Collection Features

• Tool Grouping - Add up to 100 tools per collection
• Custom Ordering - Arrange tools in your preferred order
• Tool Notes - Add notes explaining why each tool is included
• Environment Variables - Store API keys that are passed to tools at runtime
• MCP Integration - Connect to Claude Desktop with a single URL
• AI Use Cases - Auto-generate workflow suggestions

Collection Fields

Steps to Create

Adding Tools

From your collection's detail page, use the "Add Tool" button to search the registry. You can search by name, description, or category.

Tool Notes

Add notes to each tool explaining why it's in the collection or how to use it. Notes are visible to anyone viewing the collection and help provide context.

Reordering Tools

Tools are presented to AI models in the order they appear in your collection. You can drag and drop to reorder tools based on your preferred workflow.

MCP Server URLs

Each collection provides two transport options:

Claude Desktop Configuration

Add your collection to Claude Desktop's configuration file:

{
  "mcpServers": {
    "tpmjs-my-collection": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://tpmjs.com/api/mcp/YOUR_USERNAME/YOUR_COLLECTION_SLUG/http",
        "--header",
        "Authorization: Bearer YOUR_TPMJS_API_KEY"
      ]
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code CLI

claude mcp add tpmjs-my-collection \
  https://tpmjs.com/api/mcp/YOUR_USERNAME/YOUR_COLLECTION_SLUG/http \
  -t http -H "Authorization: Bearer YOUR_TPMJS_API_KEY"

Adding Environment Variables

Security

Common Variables

Basic Configuration

Advanced Settings

Example System Prompt

You are a helpful research assistant specializing in web scraping and data analysis.

When asked to research a topic:
1. Use available web scraping tools to gather information
2. Analyze and synthesize the data
3. Present findings in a clear, structured format

Always cite your sources and be transparent about limitations.

Individual Tools

From your agent's detail page, use the "Add Tool" button to search and attach specific tools. Each tool appears with its name, description, and required environment variables.

Attaching Collections

You can attach entire collections to your agent. When a collection is attached, the agent can use all tools in that collection. This is useful for grouping related tools.

Tool Limits

• Maximum 50 individual tools per agent
• Maximum 10 collections per agent
• Tools from attached collections don't count against the 50 tool limit

Features

Chat URLs

What Gets Forked

How to Fork an Agent

Fork Button States

How to Fork a Collection

Collection Fork Limits

• Maximum 50 collections per user
• Forked collections start as private
• New MCP URLs are generated for your fork

Forked From Badge

Forked items display a "Forked from" badge linking back to the original. This provides attribution and lets users discover the source.

Fork Count

Public agents and collections display a fork count showing how many times they've been forked. This indicates popularity and usefulness to the community.

How to View Parent Changes

What You Can See

When you visit the parent, you'll see its current state:

Manual Updates

TPMJS uses a manual update model—your fork doesn't automatically sync with the parent. To incorporate parent changes:

API Access

You can also fetch parent information via the API:

# Get a public agent's current tools
curl "https://tpmjs.com/api/public/users/{username}/agents/{uid}"

# Response includes current tools and collections:
{
  "id": "...",
  "name": "Research Assistant",
  "tools": [...],        // Current attached tools
  "collections": [...],  // Current attached collections
  "forkedFromId": "...", // Your fork has this pointing to parent
  "forkedFrom": { ... }  // Parent info (if you're viewing your fork)
}

Key Format

TPMJS API keys follow a consistent format for easy identification:

tpmjs_sk_abc123def456ghi789...

• tpmjs_sk_ prefix identifies the key type
• 32 random bytes encoded as base64url
• Shown in full only once at creation time
• Displayed as prefix only (e.g., tpmjs_sk_abc1...) in the dashboard

Steps to Create

Key Management

Available Scopes

Using API Keys

Include your API key in the Authorization header:

Authorization: Bearer tpmjs_sk_your_api_key_here

Example request:

curl -H "Authorization: Bearer tpmjs_sk_your_api_key" \
  "https://tpmjs.com/api/agents"

Limits by Tier

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1704067200

Handling Rate Limits

When rate limited, you'll receive a 429 response with a Retry-After header:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again in 60 seconds."
  }
}

What's Tracked

• Request Count - Total API calls per period
• Token Usage - Input/output tokens for agent conversations
• Latency - Average response time per endpoint
• Error Rate - Percentage of failed requests
• Cost Estimation - Estimated LLM costs based on token usage

Usage Dashboard

View detailed usage analytics at Dashboard → Usage. The dashboard shows:

• Time-series graphs of requests and tokens
• Breakdown by endpoint and API key
• Hourly, daily, and monthly aggregations
• Cost estimates based on provider pricing

Data Retention

• Individual Records - Kept for 30 days
• Aggregated Summaries - Kept indefinitely

Why This Model?

• Security - Owner credentials stay private, never shared with callers
• Transparency - Callers pay for their own LLM/tool usage
• Flexibility - Use public resources without forking
• Control - Fork when you want to customize

Accessing Your Own Agent

As the owner, just send your message—your stored LLM key and env vars are used:

POST /api/agents/{agentId}/conversation/{conversationId}
Authorization: Bearer YOUR_TPMJS_API_KEY

{
  "message": "Hello, help me with..."
}

Accessing Someone Else's Public Agent

You must provide your own LLM provider key and any tool environment variables:

POST /api/agents/{agentId}/conversation/{conversationId}
Authorization: Bearer YOUR_TPMJS_API_KEY

{
  "message": "Hello, help me with...",
  "providerApiKey": "sk-your-openai-key...",
  "env": {
    "UNSANDBOX_API_KEY": "your-unsandbox-key",
    "FIRECRAWL_API_KEY": "your-firecrawl-key"
  }
}

Missing Provider API Key

If you don't provide providerApiKey for a public agent:

{
  "success": false,
  "error": "Public agent access requires your own API key",
  "details": {
    "code": "MISSING_PROVIDER_KEY",
    "requiredProvider": "OPENAI",
    "hint": "Provide your OPENAI API key in the 'providerApiKey' field"
  }
}
// HTTP 400 Bad Request

Missing Environment Variables

If the agent's tools require env vars you didn't provide:

{
  "success": false,
  "error": "Missing required environment variables",
  "details": {
    "code": "MISSING_ENV_VARS",
    "missingVars": [
      { "name": "UNSANDBOX_API_KEY", "description": "API key for code execution" },
      { "name": "FIRECRAWL_API_KEY", "description": "API key for web scraping" }
    ],
    "hint": "Provide these variables in the 'env' field of your request"
  }
}
// HTTP 400 Bad Request

Who Pays?

Accessing Your Own Collection

As the owner, just make MCP calls—your stored env vars are used:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tpmjs-unsandbox-executeCode",
    "arguments": { "code": "print('hello')" }
  },
  "id": 1
}

Accessing Someone Else's Public Collection

You must provide environment variables in the env field of params:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tpmjs-unsandbox-executeCode",
    "arguments": { "code": "print('hello')" },
    "env": {
      "UNSANDBOX_API_KEY": "your-unsandbox-key"
    }
  },
  "id": 1
}

Missing Environment Variables

If you don't provide required env vars:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Missing required environment variables",
    "data": {
      "missingVars": [
        { "name": "UNSANDBOX_API_KEY", "description": "API key for code execution" }
      ]
    }
  }
}

Who Pays?

User Limits

Collection Limits

Agent Limits

Conversation Limits