Skill v1.0.1
currentAutomated scan98/10012 files
version: "1.0.1" name: typescript-mcp description: "MCP servers with TypeScript on Cloudflare Workers using @modelcontextprotocol/sdk. Use for API integrations, stateless tools, edge deployments, or encountering export syntax, schema validation, memory leak, CORS, auth errors." license: MIT metadata: version: 2.0.0 last_updated: 2025-12-17 optimization_date: 2025-12-17 token_savings: ~55% sdk_version: "@modelcontextprotocol/sdk@1.22.0" platform: cloudflare-workers production_tested: true errors_prevented: 13 keywords:
- mcp
- model context protocol
- typescript mcp
- cloudflare workers mcp
- mcp server
- mcp tools
- mcp resources
- mcp sdk
- "@modelcontextprotocol/sdk"
- hono mcp
- streamablehttpservertransport
- mcp authentication
- mcp cloudflare
- edge mcp server
- serverless mcp
- typescript mcp server
- mcp api
- llm tools
- ai tools
- cloudflare d1 mcp
- cloudflare kv mcp
- mcp testing
- mcp deployment
- wrangler mcp
- export syntax error
- schema validation error
- memory leak mcp
- cors mcp
- rate limiting mcp
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
TypeScript MCP Server on Cloudflare Workers
Build production-ready Model Context Protocol (MCP) servers using TypeScript and deploy them on Cloudflare Workers. This skill covers the official @modelcontextprotocol/sdk, HTTP transport setup, authentication patterns, Cloudflare service integrations, and comprehensive error prevention.
When to Use This Skill
Use this skill 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
Do NOT use this skill 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)
Secure Installation
MCP server packages grant tool access to LLMs — a compromised SDK can expose full system control. Verify packages before installing. Follow supply chain security best practices:
- Block post-install scripts —
npm config set ignore-scripts true(or Bun: disabled by default) - Cooldown period — Wait 7 days for new package versions to be vetted by the community
- Audit before installing — Run
socket package score npm <pkg>or usesocket npm install <pkg>to check packages
Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
Core Concepts
MCP Protocol Components:
- Tools - Functions LLMs can invoke (Zod schemas, async handlers, external APIs)
- Resources - Data exposure (URI-based:
config://app,user://{userId}) - Prompts - Pre-configured templates for LLM interactions
- Completions - Argument auto-complete (optional)
Quick Start
1. Install Dependencies
bun add @modelcontextprotocol/sdk hono zodbun add -d @cloudflare/workers-types wrangler typescript
2. Create Basic MCP Server
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';import { Hono } from 'hono';import { z } from 'zod';const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });// Register a toolserver.registerTool('echo',{description: 'Echoes back the input text',inputSchema: z.object({ text: z.string().describe('Text to echo') })},async ({ text }) => ({ content: [{ type: 'text', text }] }));// HTTP endpointconst app = new Hono();app.post('/mcp', async (c) => {const transport = new StreamableHTTPServerTransport({sessionIdGenerator: undefined,enableJsonResponse: true});// CRITICAL: Close transport to prevent memory leaksc.res.raw.on('close', () => transport.close());await server.connect(transport);await transport.handleRequest(c.req.raw, c.res.raw, await c.req.json());return c.body(null);});export default app;
3. Deploy
wrangler deploy
4. Use Production Templates
For complete implementations, copy from templates/ directory:
templates/basic-mcp-server.ts- Minimal working servertemplates/tool-server.ts- Multiple tools (API integrations, calculations)templates/resource-server.ts- Static and dynamic resourcestemplates/full-server.ts- Complete server (tools + resources + prompts)templates/authenticated-server.ts- Production security with API key authenticationtemplates/wrangler.jsonc- Cloudflare Workers configuration
Authentication Patterns
Quick Example - API Key Authentication (Most Common):
app.use('/mcp', async (c, next) => {const authHeader = c.req.header('Authorization');if (!authHeader?.startsWith('Bearer ')) {return c.json({ error: 'Unauthorized' }, 401);}const apiKey = authHeader.replace('Bearer ', '');const isValid = await c.env.MCP_API_KEYS.get(`key:${apiKey}`);if (!isValid) return c.json({ error: 'Invalid API key' }, 403);await next();});
For complete authentication guide: Load references/authentication-guide.md when implementing production authentication. Covers 5 methods: API Key (recommended), Cloudflare Zero Trust Access, OAuth 2.0, JWT custom, and mTLS. Includes security best practices, testing strategies, and migration guides.
Cloudflare Service Integration
Quick Example - D1 Database Tool:
server.registerTool('query-database',{description: 'Executes SQL query on D1 database',inputSchema: z.object({query: z.string(),params: z.array(z.union([z.string(), z.number()])).optional()})},async ({ query, params }, env) => {const result = await env.DB.prepare(query).bind(...(params || [])).all();return { content: [{ type: 'text', text: JSON.stringify(result.results, null, 2) }] };});
Supported Services: D1 (SQL Database), KV (Key-Value Store), R2 (Object Storage), Vectorize (Vector Database), Workers AI, Queues, Analytics Engine.
For complete integration guide: Load references/cloudflare-integration.md when integrating Cloudflare services. Includes setup, MCP tool examples, best practices, and advanced patterns (RAG systems, combining services).
Testing Strategies
Quick Testing Workflow:
- Unit Tests (Vitest): Test tool logic in isolation
- Integration Tests (MCP Inspector): Test with
bunx @modelcontextprotocol/inspector - E2E Tests: Test with real MCP clients
# Local devnpm run dev# Test with Inspectorbunx @modelcontextprotocol/inspector
For complete testing guide: Load references/testing-guide.md when writing tests. Covers unit testing with Vitest, integration testing with MCP Inspector, E2E testing, authentication testing, load testing with Artillery, mocking external APIs, and CI/CD testing patterns.
Known Issues Prevention
This skill prevents 13 documented errors. Here are the top 5 most critical:
Issue #1: Export Syntax Issues (CRITICAL)
Error: "Cannot read properties of undefined (reading 'map')" Source: honojs/hono#3955 Prevention:
// ❌ WRONG // ✅ CORRECTexport default { fetch: app.fetch }; export default app;
Issue #2: Unclosed Transport Connections
Error: Memory leaks, hanging connections Prevention:
app.post('/mcp', async (c) => {const transport = new StreamableHTTPServerTransport({...});c.res.raw.on('close', () => transport.close()); // CRITICAL// ... handle request});
Issue #3: Tool Schema Validation Failure
Error: ListTools request handler fails to generate inputSchema Source: modelcontextprotocol/typescript-sdk#1028 Prevention: Pass Zod schema directly - SDK handles conversion automatically
server.registerTool('tool', { inputSchema: z.object({...}) }, handler);
Issue #4: Tool Arguments Not Passed to Handler
Error: Handler receives undefined arguments Source: modelcontextprotocol/typescript-sdk#1026 Prevention: Use z.infer<typeof schema> for type-safe handler parameters
Issue #5: CORS Misconfiguration
Error: Browser clients can't connect Prevention:
import { cors } from 'hono/cors';app.use('/mcp', cors({ origin: ['http://localhost:3000'], allowMethods: ['POST', 'OPTIONS'] }));
For complete error catalog: Load references/common-errors.md when debugging. Covers all 13 errors with detailed solutions, root causes from GitHub issues, and debugging checklist.
Deployment Workflow
Quick Deployment:
# Local developmentnpm run dev # Server at http://localhost:8787/mcp# Productionnpm run buildwrangler deploy# Specific environmentwrangler deploy --env production
For complete deployment guide: Load references/deployment-guide.md when setting up production. Covers environment setup (dev/staging/prod), multiple environments, custom domains, CI/CD with GitHub Actions, database migrations, monitoring & logs, rollback strategy, performance optimization, health checks, cost optimization, security checklist, and troubleshooting.
Package Versions (Verified 2025-10-28)
{"dependencies": {"@modelcontextprotocol/sdk": "^1.20.2","@cloudflare/workers-types": "^4.20251011.0","hono": "^4.10.1","zod": "^4.1.12"},"devDependencies": {"@cloudflare/vitest-pool-workers": "^0.5.29","vitest": "^3.0.0","wrangler": "^4.43.0","typescript": "^5.7.0"}}
When to Use Cloudflare Agents SDK Instead
Use Cloudflare Agents MCP when you need:
- Stateful agents with persistent storage (SQLite up to 1GB)
- WebSocket support for real-time bidirectional communication
- Long-running sessions with conversation history
- Scheduled agent tasks with Durable Objects alarms
- Global distribution with automatic state replication
Use this skill (standalone TypeScript MCP) when you need:
- Stateless tools and API integrations
- Edge deployment with minimal cold start latency
- Simple authentication (API keys, OAuth)
- Pay-per-request pricing (no Durable Objects overhead)
- Maximum portability (works on any platform, not just Cloudflare)
See references/cloudflare-agents-vs-standalone.md for detailed comparison.
When to Load References
Load reference files when working on specific aspects of TypeScript MCP servers:
authentication-guide.md
Load when:
- Setup-based: Implementing authentication for production MCP server
- Method-based: Choosing between API Key, OAuth 2.0, Zero Trust, JWT, or mTLS
- Security-based: Implementing rate limiting, API key rotation, audit logging
- Testing-based: Writing authentication tests (unit, integration, E2E)
- Migration-based: Upgrading from one auth method to another
cloudflare-agents-vs-standalone.md
Load when:
- Decision-based: Choosing between standalone MCP and Cloudflare Agents SDK
- Architecture-based: Need stateful agents vs stateless tools
- Cost-based: Comparing pricing for low/high traffic scenarios
- Feature-based: Need WebSockets, persistent storage, or scheduled tasks
- Migration-based: Moving from standalone to Agents SDK or vice versa
cloudflare-integration.md
Load when:
- Service-based: Integrating D1, KV, R2, Vectorize, Workers AI, Queues, or Analytics Engine
- Pattern-based: Building RAG systems or multi-service applications
- Setup-based: Configuring wrangler.jsonc bindings for Cloudflare services
- Example-based: Need working code for specific service integration
common-errors.md
Load when:
- Error-based: Encountering any of the 13 documented errors
- Debugging-based: Server not working, need systematic debugging checklist
- Prevention-based: Want to prevent all known issues before deployment
- Source-based: Need GitHub issue references for specific errors
deployment-guide.md
Load when:
- CI/CD-based: Setting up GitHub Actions for automated deployment
- Environment-based: Configuring staging/production environments
- Migration-based: Running D1 database migrations in CI/CD
- Monitoring-based: Setting up logs, analytics, health checks
- Optimization-based: Implementing caching, performance optimization, cost reduction
testing-guide.md
Load when:
- Testing-based: Writing unit tests, integration tests, or E2E tests
- Tool-based: Using Vitest, MCP Inspector, or Artillery for testing
- CI/CD-based: Setting up automated testing in GitHub Actions
- Authentication-based: Testing authentication middleware
- Load-based: Need to load test MCP server endpoints
tool-patterns.md
Load when:
- Pattern-based: Implementing external API wrappers, database queries, file operations
- Example-based: Need production-tested tool implementation examples
- Architecture-based: Building multi-step operations, streaming responses, caching tools
- Error-based: Need error handling best practices for tools
- Response-based: Understanding tool response formats
Using Bundled Resources
Templates (templates/): Production-ready implementations
basic-mcp-server.ts- Minimal working servertool-server.ts- Multiple tools (API integrations)resource-server.ts- Static and dynamic resourcesfull-server.ts- Complete server (tools + resources + prompts)authenticated-server.ts- Production securitywrangler.jsonc- Cloudflare Workers configuration
Reference Guides (references/): Comprehensive documentation (see "When to Load References" section above)
tool-patterns.md- Implementation patternsauthentication-guide.md- All 5 auth methodstesting-guide.md- Unit, integration, E2E testingdeployment-guide.md- CI/CD, environments, monitoringcloudflare-integration.md- D1, KV, R2, Vectorize, Workers AIcommon-errors.md- All 13 errors + debuggingcloudflare-agents-vs-standalone.md- Decision matrix
Scripts (scripts/): Automation tools
init-mcp-server.sh- Initialize new projecttest-mcp-connection.sh- Test 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/
- Context7 Library ID:
/websites/modelcontextprotocol(if available)
Example Servers:
- Official examples: https://github.com/modelcontextprotocol/servers
- Cloudflare MCP server: https://github.com/cloudflare/mcp-server-cloudflare
Critical Rules
Always Do: ✅ Close transport on response end | ✅ Use export default app syntax | ✅ Implement authentication | ✅ Add rate limiting | ✅ Use Zod schemas | ✅ Test with MCP Inspector | ✅ Update to SDK v1.20.2+ | ✅ Document all tools | ✅ Handle errors gracefully | ✅ Use environment variables
Never Do: ❌ Object wrapper export | ❌ Forget to close transport | ❌ Deploy without auth | ❌ Log env variables | ❌ Use CommonJS | ❌ Skip CORS config | ❌ Hardcode credentials | ❌ Return raw errors | ❌ Deploy untested | ❌ Use outdated SDK
Complete Setup Checklist
Use this checklist to verify your MCP server setup:
- [ ] SDK version is 1.20.2 or later
- [ ] Export syntax is correct (direct export, not object wrapper)
- [ ] Transport is closed on response end
- [ ] Authentication is implemented (if production)
- [ ] Rate limiting is configured (if public-facing)
- [ ] CORS headers are set (if browser clients)
- [ ] All tools have clear descriptions and Zod schemas
- [ ] Environment variables are used for secrets
- [ ] wrangler.jsonc includes all necessary bindings
- [ ] Local testing with
wrangler devsucceeds - [ ] MCP Inspector can connect and list tools
- [ ] Production deployment succeeds
- [ ] All tools/resources return expected responses
Production Example
This skill is based on patterns from:
- Official MCP TypeScript SDK examples: https://github.com/modelcontextprotocol/servers
- Cloudflare MCP server: https://github.com/cloudflare/mcp-server-cloudflare
- Errors: 0 (all 10+ known issues prevented)
- Token Savings: ~70% vs manual implementation
- Validation: ✅ All templates tested on Cloudflare Workers
Questions? Issues?
- Check
references/common-errors.mdfor troubleshooting - Verify all steps in the Quick Start section
- Test with MCP Inspector:
bunx @modelcontextprotocol/inspector - Check official docs: https://spec.modelcontextprotocol.io/
- Ensure SDK version is 1.20.2 or later
Last Updated: 2025-10-28 SDK Version: @modelcontextprotocol/sdk@1.20.2 Maintainer: Claude Skills Repository