Package Exports

@teachmeto/api-mcp
@teachmeto/api-mcp/build/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@teachmeto/api-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@teachmeto/api-mcp

Official Model Context Protocol (MCP) server for the TeachMeTo API. Access 76+ TeachMeTo tools through Claude Desktop or any MCP-compatible client.

Features

76+ TeachMeTo API Tools - Bookings, users, locations, payments, subscriptions, and more
OAuth 2.1 Authentication - Secure token-based authentication with JWT support
Multiple Transport Modes - Stdio (Claude Desktop) and HTTP (backend integrations)
Type-Safe - Full TypeScript implementation with strict mode
Registry-Based Architecture - Automatic tool discovery and registration
Rate Limiting - Built-in protection with configurable limits

Installation

npm install @teachmeto/api-mcp

Quick Start

Claude Desktop (Stdio Mode)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "teachmeto": {
      "command": "node",
      "args": ["/path/to/node_modules/@teachmeto/api-mcp/build/index.js"],
      "env": {
        "TEACHMETO_API_URL": "https://api.teachme.to",
        "TEACHMETO_JWT_PUBLIC_KEY": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
      }
    }
  }
}

HTTP Mode (Backend Integration)

# Start HTTP server
PORT=3001 node node_modules/@teachmeto/api-mcp/build/http-server.js

Authentication

Stdio Mode (Claude Desktop)

Start conversation with Claude
Request OTP: "Request OTP for +1234567890"
Verify OTP: "Verify OTP 123456"
Use authenticated tools automatically

HTTP Mode

The server provides OAuth 2.1 endpoints for backend integration:

POST /oauth/register - Register OAuth client
POST /oauth/token - Exchange TeachMeTo JWT for MCP access token
GET /.well-known/oauth-authorization-server - OAuth metadata

See full OAuth 2.1 documentation in the repository.

Configuration

Environment Variables

# Required
TEACHMETO_API_URL=https://api.teachme.to
TEACHMETO_JWT_PUBLIC_KEY='-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'

# Optional
LOG_LEVEL=info                    # debug, info, warn, error
RATE_LIMIT_RPM=100               # Requests per minute
RATE_LIMIT_BURST=10              # Burst limit
PORT=3001                        # HTTP server port
NODE_ENV=development             # Environment

# Tool Filtering
DISABLE_WRITE_OPERATIONS=false   # Disable all POST/PUT/DELETE/PATCH
DISABLED_TOOLS=                  # Comma-separated tool names
DISABLED_CATEGORIES=             # Comma-separated categories

Tool Filtering

Disable specific tools or categories for security:

# Conservative mode - read-only
DISABLE_WRITE_OPERATIONS=true npm start

# Disable specific tools
DISABLED_TOOLS=cancel_booking,delete_user npm start

# Disable entire categories
DISABLED_CATEGORIES=admin,payments npm start

Usage Examples

List Bookings

User: Show me my upcoming bookings
Claude: [calls list_bookings tool] → Returns user's bookings

Search Listings

User: Find tennis coaches in San Francisco
Claude: [calls search_listings_by_location tool] → Returns matching listings

Create Booking

User: Book a tennis lesson with coach John tomorrow at 2pm
Claude: [calls create_booking tool] → Creates booking and returns confirmation

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Run HTTP server
npm run dev:http

# Type checking
npm run type-check

# Run tests
npm test

Transport Modes

Stdio (Default)

For Claude Desktop and MCP clients
Single-user persistent sessions
Automatic JWT session management
Command: node build/index.js

HTTP

For backend integrations
Multi-user with OAuth 2.1
RESTful tool execution
Command: node build/http-server.js

SSE (Server-Sent Events)

For streaming responses
Long-lived connections
Command: node build/http-sse-server.js

Security

JWT Validation - RS256/ES256 signature verification
Rate Limiting - Configurable per-minute and burst limits
Token Expiry - Short-lived MCP tokens (15 minutes)
Audience Binding - Tokens bound to specific resources
Tool Filtering - Disable write operations or specific tools

Requirements

Node.js >= 18.0.0
npm >= 8.0.0