>_
Marketplace

Unnamed Skill

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.

$ インストール

git clone https://github.com/secondsky/claude-skills /tmp/claude-skills && cp -r /tmp/claude-skills/plugins/typescript-mcp/skills/typescript-mcp ~/.claude/skills/claude-skills

// tip: Run this command in your terminal to install the skill

SKILL.md
View on GitHub →

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.

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 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 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)

Core Concepts

MCP Protocol Components:

  1. Tools - Functions LLMs can invoke (Zod schemas, async handlers, external APIs)
  2. Resources - Data exposure (URI-based: config://app, user://{userId})
  3. Prompts - Pre-configured templates for LLM interactions
  4. Completions - Argument auto-complete (optional)

Quick Start

1. Install Dependencies

bun add @modelcontextprotocol/sdk hono zod
bun 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 tool
server.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 endpoint
const app = new Hono();

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  // CRITICAL: Close transport to prevent memory leaks
  c.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 server
  • templates/tool-server.ts - Multiple tools (API integrations, calculations)
  • templates/resource-server.ts - Static and dynamic resources
  • templates/full-server.ts - Complete server (tools + resources + prompts)
  • templates/authenticated-server.ts - Production security with API key authentication
  • templates/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:

  1. Unit Tests (Vitest): Test tool logic in isolation
  2. Integration Tests (MCP Inspector): Test with bunx @modelcontextprotocol/inspector
  3. E2E Tests: Test with real MCP clients
# Local dev
npm run dev

# Test with Inspector
bunx @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                      // ✅ CORRECT
export 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 development
npm run dev  # Server at http://localhost:8787/mcp

# Production
npm run build
wrangler deploy

# Specific environment
wrangler 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 server
  • tool-server.ts - Multiple tools (API integrations)
  • resource-server.ts - Static and dynamic resources
  • full-server.ts - Complete server (tools + resources + prompts)
  • authenticated-server.ts - Production security
  • wrangler.jsonc - Cloudflare Workers configuration

Reference Guides (references/): Comprehensive documentation (see "When to Load References" section above)

  • tool-patterns.md - Implementation patterns
  • authentication-guide.md - All 5 auth methods
  • testing-guide.md - Unit, integration, E2E testing
  • deployment-guide.md - CI/CD, environments, monitoring
  • cloudflare-integration.md - D1, KV, R2, Vectorize, Workers AI
  • common-errors.md - All 13 errors + debugging
  • cloudflare-agents-vs-standalone.md - Decision matrix

Scripts (scripts/): Automation tools

  • init-mcp-server.sh - Initialize new project
  • test-mcp-connection.sh - Test server connectivity

Official Documentation

Example Servers:

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 dev succeeds
  • 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:

Questions? Issues?

  1. Check references/common-errors.md for troubleshooting
  2. Verify all steps in the Quick Start section
  3. Test with MCP Inspector: bunx @modelcontextprotocol/inspector
  4. Check official docs: https://spec.modelcontextprotocol.io/
  5. 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

Repository

secondsky
secondsky
Author
secondsky/claude-skills/plugins/typescript-mcp/skills/typescript-mcp
9
Stars
0
Forks
Updated4d ago
Added1w ago

Actions

View on GitHubDownload ZIPReport Issue

Related Skills

skill-writer
pytorch/pytorch
95.4k
docstring
pytorch/pytorch
95.4k
at-dispatch-v2
pytorch/pytorch
95.4k
add-uint-support
pytorch/pytorch
95.4k
skill-creator
openai/codex
54.7k