TypeScript MCP Server for Cloudflare Workers

Status: Production Ready ✅ Last Updated: 2026-01-03 Production Tested: Official MCP SDK examples + Cloudflare MCP server

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• typescript mcp
• mcp server
• model context protocol
• @modelcontextprotocol/sdk
• mcp typescript
• cloudflare mcp
• workers mcp
• mcp tools
• mcp resources
• mcp prompts
• mcp tasks
• mcp sampling
• mcp long-running
• streamablehttpservertransport
• mcpserver

Secondary Keywords

• llm tools
• ai tools cloudflare
• edge mcp
• serverless mcp
• hono mcp
• mcp api
• mcp endpoint
• mcp protocol
• mcp sdk typescript
• cloudflare workers mcp server
• deploy mcp server
• mcp authentication
• mcp cloudflare d1
• mcp cloudflare kv
• mcp cloudflare r2

Error-Based Keywords

• "Cannot read properties of undefined (reading 'map')"
• export syntax error mcp
• mcp schema validation failure
• mcp tool arguments undefined
• mcp cors error
• mcp memory leak
• streamablehttp transport not closed
• mcp authentication bypass
• typescript compilation memory
• uri template redos

---

What This Skill Does

Provides production-ready patterns for building Model Context Protocol (MCP) servers with TypeScript on Cloudflare Workers, using the official @modelcontextprotocol/sdk. Prevents 10+ common errors including export syntax issues, schema validation failures, memory leaks, CORS misconfigurations, and authentication vulnerabilities.

Core Capabilities

✅ Complete templates for basic, tool-only, resource-only, authenticated, and full MCP servers ✅ Error prevention for 10+ documented production issues with GitHub issue sources ✅ Authentication patterns for API keys, OAuth 2.0, Zero Trust, and JWT ✅ Cloudflare integrations for D1, KV, R2, Vectorize, Workers AI, and Queues ✅ Testing strategies including unit tests, MCP Inspector, and E2E testing ✅ Deployment workflows with Wrangler, CI/CD, and multi-environment support ✅ Reference documentation for tool patterns, auth, testing, deployment, and integrations ✅ Package versions verified current as of 2025-10-28

---

Known Issues This Skill Prevents

---

When to Use This Skill

✅ Use When:

• Building MCP servers to expose APIs, tools, or data to LLMs
• Deploying serverless MCP endpoints on Cloudflare Workers
• Integrating external APIs as MCP tools (REST, GraphQL, databases)
• Creating stateless MCP servers for edge deployment
• Exposing Cloudflare services (D1, KV, R2, Vectorize) via MCP protocol
• Implementing authenticated MCP servers with API keys, OAuth, or Zero Trust
• Building multi-tool MCP servers with resources and prompts
• Needing production-ready templates that prevent common MCP errors

❌ Don't Use When:

• Building Python MCP servers (use FastMCP skill instead)
• Needing stateful agents with WebSockets (use Cloudflare Agents SDK)
• Wanting long-running persistent agents with SQLite storage (use Durable Objects)
• Building local CLI tools (use stdio transport, not HTTP)

---

Quick Usage Example

# Use the init script to create a new MCP server
cd ~/.claude/skills/typescript-mcp/scripts
./init-mcp-server.sh my-mcp-server

# Select template (1-5)
# Script creates project with:
# - package.json with all dependencies
# - src/index.ts with selected template
# - wrangler.jsonc configuration
# - tsconfig.json, .gitignore, README

# Navigate to project
cd my-mcp-server

# Run locally
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8787/mcp

# Deploy to Cloudflare
npm run deploy

Result: Production-ready MCP server with zero errors, proper authentication, and all best practices implemented.

Full instructions: See SKILL.md

---

Token Efficiency Metrics

---

Package Versions (Verified 2026-01-03)

---

Dependencies

Prerequisites: None

Integrates With:

• cloudflare-worker-base (optional - base Workers setup)
• cloudflare-d1 (optional - D1 database patterns)
• cloudflare-kv (optional - KV storage patterns)
• cloudflare-r2 (optional - R2 object storage)
• cloudflare-vectorize (optional - vector search)
• cloudflare-workers-ai (optional - AI model inference)

---

File Structure

typescript-mcp/
├── SKILL.md                  # Complete documentation
├── README.md                 # This file
├── templates/                # Production-ready templates
│   ├── basic-mcp-server.ts             # Minimal server (echo tool)
│   ├── tool-server.ts                  # Multiple tools (API integrations)
│   ├── resource-server.ts              # Resources only (data exposure)
│   ├── full-server.ts                  # Complete (tools + resources + prompts)
│   ├── authenticated-server.ts         # With API key auth
│   ├── tasks-server.ts                 # Tasks for long-running ops (v1.24.0+)
│   └── wrangler.jsonc                  # Cloudflare Workers config
├── references/               # Advanced documentation
│   ├── tool-patterns.md                # Common tool implementations
│   ├── authentication-guide.md         # All auth methods
│   ├── testing-guide.md                # Unit, integration, E2E testing
│   ├── deployment-guide.md             # Wrangler workflows + CI/CD
│   ├── cloudflare-integration.md       # D1, KV, R2, Vectorize, AI
│   ├── common-errors.md                # 10+ errors with solutions
│   └── cloudflare-agents-vs-standalone.md  # Decision guide
└── scripts/                  # Automation scripts
    ├── init-mcp-server.sh              # Initialize new MCP project
    └── test-mcp-connection.sh          # Test MCP server connectivity

---

Official Documentation

• MCP Specification: https://spec.modelcontextprotocol.io/
• TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
• Cloudflare Workers: https://developers.cloudflare.com/workers/
• Hono Framework: https://hono.dev/
• Example Servers: https://github.com/modelcontextprotocol/servers
• Cloudflare MCP Server: https://github.com/cloudflare/mcp-server-cloudflare

---

Related Skills

• cloudflare-worker-base - Base Cloudflare Workers setup with Hono
• cloudflare-d1 - D1 SQL database patterns and migrations
• cloudflare-kv - KV key-value storage patterns
• cloudflare-r2 - R2 object storage (S3-compatible)
• cloudflare-vectorize - Vector database for RAG and semantic search
• cloudflare-workers-ai - Workers AI model inference
• fastmcp - Python MCP servers (alternative approach)

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/jezweb/claude-skills/issues
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: Official MCP SDK examples + Cloudflare MCP server Token Savings: ~70% Error Prevention: 100% (all 10+ documented issues prevented) Ready to use! See SKILL.md for complete setup.