typescript-mcp

Original：🇺🇸 English
Translated

Use this skill when building MCP (Model Context Protocol) servers with TypeScript on Cloudflare Workers. This skill provides production-tested patterns for implementing tools, resources, and prompts using the official @modelcontextprotocol/sdk. It prevents 10+ common errors including export syntax issues, schema validation failures, memory leaks from unclosed transports, CORS misconfigurations, and authentication vulnerabilities. This skill should be used when developers need stateless MCP servers for API integrations, external tool exposure, or serverless edge deployments. For stateful agents with WebSockets and persistent storage, consider the Cloudflare Agents SDK instead. Supports multiple authentication methods (API keys, OAuth, Zero Trust), Cloudflare service integrations (D1, KV, R2, Vectorize), and comprehensive testing strategies. Production tested with token savings of ~70% vs manual implementation. 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

32installs
Sourcejackspace/claudeskillz
Added on

NPX Install

npx skill4agent add jackspace/claudeskillz typescript-mcp

Tags

Translated version includes tags in frontmatter
mcp-servercloudflare-workerstypescriptllm-toolsauthentication-patterns

SKILL.md Content

View Translation Comparison →

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
  • Input/output schemas defined with Zod
  • Async handlers return structured content
  • Can call external APIs, databases, or computations
2. Resources - Static or dynamic data exposure
  • URI-based addressing (e.g., 
    config://app/settings
    )
  • Templates support parameters (e.g., 
    user://{userId}
    )
  • Return text, JSON, or binary data
3. Prompts - Pre-configured prompt templates
  • Provide reusable conversation starters
  • Can include placeholders and dynamic content
  • Help standardize LLM interactions
4. Completions (Optional) - Argument auto-complete
  • Suggest valid values for tool arguments
  • Improve developer experience

Quick Start

1. Basic MCP Server Template

Use the 
basic-mcp-server.ts
template for a minimal working server:
typescript
// See templates/basic-mcp-server.ts
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 simple tool
server.registerTool(
  'echo',
  {
    description: 'Echoes back the input text',
    inputSchema: z.object({
      text: z.string().describe('Text to echo back')
    })
  },
  async ({ text }) => ({
    content: [{ type: 'text', text }]
  })
);

// HTTP endpoint setup
const app = new Hono();

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

  // CRITICAL: Close transport on response end 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;
Install dependencies:
bash
npm install @modelcontextprotocol/sdk hono zod
npm install -D @cloudflare/workers-types wrangler typescript
Deploy:
bash
wrangler deploy

2. Tool-Server Template

Use 
tool-server.ts
for exposing multiple tools (API integrations, calculations):
typescript
// Example: Weather API tool
server.registerTool(
  'get-weather',
  {
    description: 'Fetches current weather for a city',
    inputSchema: z.object({
      city: z.string().describe('City name'),
      units: z.enum(['metric', 'imperial']).default('metric')
    })
  },
  async ({ city, units }, env) => {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units}&appid=${env.WEATHER_API_KEY}`
    );
    const data = await response.json();

    return {
      content: [{
        type: 'text',
        text: `Temperature in ${city}: ${data.main.temp}°${units === 'metric' ? 'C' : 'F'}`
      }]
    };
  }
);

3. Resource-Server Template

Use 
resource-server.ts
for exposing data:
typescript
import { ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';

// Static resource
server.registerResource(
  'config',
  new ResourceTemplate('config://app', { list: undefined }),
  { description: 'Application configuration' },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: 'application/json',
      text: JSON.stringify({ version: '1.0.0', features: ['tool1', 'tool2'] })
    }]
  })
);

// Dynamic resource with parameter
server.registerResource(
  'user-profile',
  new ResourceTemplate('user://{userId}', { list: undefined }),
  { description: 'User profile data' },
  async (uri, { userId }, env) => {
    const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();

    return {
      contents: [{
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(user)
      }]
    };
  }
);

4. Authenticated Server Template

Use 
authenticated-server.ts
for production security:
typescript
import { Hono } from 'hono';

const app = new Hono();

// API Key authentication middleware
app.use('/mcp', async (c, next) => {
  const authHeader = c.req.header('Authorization');
  if (!authHeader || !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();
});

app.post('/mcp', async (c) => {
  // MCP server logic (user is authenticated)
  // ... transport setup and handling
});

Authentication Patterns

Pattern 1: API Key (Recommended for Most Cases)

Setup:
  1. Create KV namespace: 
    wrangler kv namespace create MCP_API_KEYS
  2. Add to 
    wrangler.jsonc
    :
jsonc
{
  "kv_namespaces": [
    { "binding": "MCP_API_KEYS", "id": "YOUR_NAMESPACE_ID" }
  ]
}
Implementation:
typescript
async function verifyApiKey(key: string, env: Env): Promise<boolean> {
  const storedKey = await env.MCP_API_KEYS.get(`key:${key}`);
  return storedKey !== null;
}
Manage keys:
bash
# Add key
wrangler kv key put --binding=MCP_API_KEYS "key:abc123" "true"

# Revoke key
wrangler kv key delete --binding=MCP_API_KEYS "key:abc123"

Pattern 2: Cloudflare Zero Trust Access

typescript
import { verifyJWT } from '@cloudflare/workers-jwt';

const jwt = c.req.header('Cf-Access-Jwt-Assertion');
if (!jwt) {
  return c.json({ error: 'Access denied' }, 403);
}

const payload = await verifyJWT(jwt, c.env.CF_ACCESS_TEAM_DOMAIN);
// User authenticated via Cloudflare Access

Pattern 3: OAuth 2.0

See 
references/authentication-guide.md
for complete OAuth implementation.

Cloudflare Service Integration

D1 Database Tool Example

typescript
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)
      }]
    };
  }
);
Wrangler config:
jsonc
{
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "..." }
  ]
}

KV Storage Tool Example

typescript
server.registerTool(
  'get-cache',
  {
    description: 'Retrieves cached value by key',
    inputSchema: z.object({ key: z.string() })
  },
  async ({ key }, env) => {
    const value = await env.CACHE.get(key);
    return {
      content: [{ type: 'text', text: value || 'Key not found' }]
    };
  }
);

R2 Object Storage Tool Example

typescript
server.registerTool(
  'upload-file',
  {
    description: 'Uploads file to R2 bucket',
    inputSchema: z.object({
      key: z.string(),
      content: z.string(),
      contentType: z.string().optional()
    })
  },
  async ({ key, content, contentType }, env) => {
    await env.BUCKET.put(key, content, {
      httpMetadata: { contentType: contentType || 'text/plain' }
    });

    return {
      content: [{ type: 'text', text: `File uploaded: ${key}` }]
    };
  }
);

Vectorize Search Tool Example

typescript
server.registerTool(
  'semantic-search',
  {
    description: 'Searches vector database',
    inputSchema: z.object({
      query: z.string(),
      topK: z.number().default(5)
    })
  },
  async ({ query, topK }, env) => {
    const embedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: query
    });

    const results = await env.VECTORIZE.query(embedding.data[0], {
      topK,
      returnMetadata: true
    });

    return {
      content: [{
        type: 'text',
        text: JSON.stringify(results.matches, null, 2)
      }]
    };
  }
);

Testing Strategies

1. Unit Testing with Vitest

typescript
import { describe, it, expect } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

describe('Calculator Tool', () => {
  it('should add two numbers', async () => {
    const server = new McpServer({ name: 'test', version: '1.0.0' });

    server.registerTool(
      'add',
      {
        description: 'Adds two numbers',
        inputSchema: z.object({
          a: z.number(),
          b: z.number()
        })
      },
      async ({ a, b }) => ({
        content: [{ type: 'text', text: String(a + b) }]
      })
    );

    // Test tool execution
    const result = await server.callTool('add', { a: 5, b: 3 });
    expect(result.content[0].text).toBe('8');
  });
});
Install:
bash
npm install -D vitest @cloudflare/vitest-pool-workers
Run:
bash
npx vitest

2. Integration Testing with MCP Inspector

bash
# Run server locally
npm run dev

# In another terminal
npx @modelcontextprotocol/inspector

# Connect to: http://localhost:8787/mcp

3. E2E Testing with Claude Agent SDK

See 
references/testing-guide.md
for comprehensive testing patterns.

Known Issues Prevention

This skill prevents 10+ production issues documented in official MCP SDK and Cloudflare repos:

Issue #1: Export Syntax Issues (CRITICAL)

Error: 
"Cannot read properties of undefined (reading 'map')"
Source: honojs/hono#3955, honojs/vite-plugins#237 Why It Happens: Incorrect export format with Vite build causes cryptic errors Prevention:
typescript
// ❌ WRONG - Causes cryptic build errors
export default { fetch: app.fetch };

// ✅ CORRECT - Direct export
export default app;

Issue #2: Unclosed Transport Connections

Error: Memory leaks, hanging connections Source: Best practice from SDK maintainers Why It Happens: Not closing StreamableHTTPServerTransport on request end Prevention:
typescript
app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport(/*...*/);

  // CRITICAL: Always close on response end
  c.res.raw.on('close', () => transport.close());

  // ... handle request
});

Issue #3: Tool Schema Validation Failure

Error: 
ListTools request handler fails to generate inputSchema
Source: GitHub modelcontextprotocol/typescript-sdk#1028 Why It Happens: Zod schemas not properly converted to JSON Schema Prevention:
typescript
// ✅ CORRECT - SDK handles Zod schema conversion automatically
server.registerTool(
  'tool-name',
  {
    inputSchema: z.object({ a: z.number() })
  },
  handler
);

// No need for manual zodToJsonSchema() unless custom validation

Issue #4: Tool Arguments Not Passed to Handler

Error: Handler receives 
undefined
arguments Source: GitHub modelcontextprotocol/typescript-sdk#1026 Why It Happens: Schema type mismatch between registration and invocation Prevention:
typescript
const schema = z.object({ a: z.number(), b: z.number() });
type Input = z.infer<typeof schema>;

server.registerTool(
  'add',
  { inputSchema: schema },
  async (args: Input) => {
    // args.a and args.b properly typed and passed
    return { content: [{ type: 'text', text: String(args.a + args.b) }] };
  }
);

Issue #5: CORS Misconfiguration

Error: Browser clients can't connect to MCP server Source: Common production issue Why It Happens: Missing CORS headers for HTTP transport Prevention:
typescript
import { cors } from 'hono/cors';

app.use('/mcp', cors({
  origin: ['http://localhost:3000', 'https://your-app.com'],
  allowMethods: ['POST', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization']
}));

Issue #6: Missing Rate Limiting

Error: API abuse, DDoS vulnerability Source: Production security best practice Why It Happens: No rate limiting on MCP endpoints Prevention:
typescript
app.post('/mcp', async (c) => {
  const ip = c.req.header('CF-Connecting-IP');
  const rateLimitKey = `ratelimit:${ip}`;

  const count = await c.env.CACHE.get(rateLimitKey);
  if (count && parseInt(count) > 100) {
    return c.json({ error: 'Rate limit exceeded' }, 429);
  }

  await c.env.CACHE.put(
    rateLimitKey,
    String((parseInt(count || '0') + 1)),
    { expirationTtl: 60 }
  );

  // Continue...
});

Issue #7: TypeScript Compilation Memory Issues

Error: 
Out of memory
during 
tsc
build Source: GitHub modelcontextprotocol/typescript-sdk#985 Why It Happens: Large dependency tree in MCP SDK Prevention:
bash
# Add to package.json scripts
"build": "NODE_OPTIONS='--max-old-space-size=4096' tsc && vite build"

Issue #8: UriTemplate ReDoS Vulnerability

Error: Server hangs on malicious URI patterns Source: GitHub modelcontextprotocol/typescript-sdk#965 (Security) Why It Happens: Regex denial-of-service in URI template parsing Prevention: Update to SDK v1.20.2 or later (includes fix)

Issue #9: Authentication Bypass

Error: Unauthenticated access to MCP tools Source: Production security best practice Why It Happens: Missing or improperly implemented authentication Prevention: Always implement authentication for production servers (see Authentication Patterns section)

Issue #10: Environment Variable Leakage

Error: Secrets exposed in error messages or logs Source: Cloudflare Workers security best practice Why It Happens: Environment variables logged or returned in responses Prevention:
typescript
// ❌ WRONG - Exposes secrets
console.log('Env:', JSON.stringify(env));

// ✅ CORRECT - Never log env objects
try {
  // ... use env.SECRET_KEY
} catch (error) {
  // Don't include env in error context
  console.error('Operation failed:', error.message);
}

Deployment Workflow

Local Development

bash
# Install dependencies
npm install

# Run locally with Wrangler
npm run dev
# or
wrangler dev

# Server available at: http://localhost:8787/mcp

Production Deployment

bash
# Build
npm run build

# Deploy to Cloudflare Workers
wrangler deploy

# Deploy to specific environment
wrangler deploy --env production

CI/CD with GitHub Actions

yaml
name: Deploy MCP Server
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm test

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Package Versions (Verified 2025-10-28)

json
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.2",
    "@cloudflare/workers-types": "^4.20251011.0",
    "hono": "^4.10.1",
    "zod": "^3.23.8",
    "zod-to-json-schema": "^3.24.1"
  },
  "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.

Using Bundled Resources

Templates (templates/)

All templates are production-ready and tested on Cloudflare Workers:
  • templates/basic-mcp-server.ts
    - Minimal working server (echo tool example)
  • templates/tool-server.ts
    - Multiple tools implementation (API integrations, calculations)
  • templates/resource-server.ts
    - Resource-only server (static and dynamic resources)
  • templates/full-server.ts
    - Complete server (tools + resources + prompts)
  • templates/authenticated-server.ts
    - Production server with API key authentication
  • templates/wrangler.jsonc
    - Cloudflare Workers configuration with all bindings
When Claude should use these: When creating a new MCP server, copy the appropriate template based on the use case (tools-only, resources-only, authenticated, or full-featured).

Reference Guides (references/)

Comprehensive documentation for advanced topics:
  • references/tool-patterns.md
    - Common tool implementation patterns (API wrappers, database queries, calculations, file operations)
  • references/authentication-guide.md
    - All authentication methods detailed (API keys, OAuth 2.0, Zero Trust, JWT)
  • references/testing-guide.md
    - Unit testing, integration testing with MCP Inspector, E2E testing with Claude Agent SDK
  • references/deployment-guide.md
    - Wrangler workflows, environment management, CI/CD with GitHub Actions
  • references/cloudflare-integration.md
    - Using D1, KV, R2, Vectorize, Workers AI, Queues, Durable Objects
  • references/common-errors.md
    - All 10+ errors with detailed solutions, root causes, and prevention strategies
  • references/cloudflare-agents-vs-standalone.md
    - Decision matrix for choosing between standalone MCP and Cloudflare Agents SDK
When Claude should load these: When developer needs advanced implementation details, debugging help, or architectural guidance.

Scripts (scripts/)

Automation scripts for initializing and testing MCP servers:
  • scripts/init-mcp-server.sh
    - Initializes new MCP server project with dependencies, wrangler config, and template selection
  • scripts/test-mcp-connection.sh
    - Tests MCP server connectivity and validates tool/resource endpoints
When Claude should use these: When setting up a new project or debugging connectivity issues.

Official Documentation

Example Servers:

Critical Rules

Always Do

✅ Close transport on response end to prevent memory leaks ✅ Use direct export syntax (
export default app
) not object wrapper ✅ Implement authentication for production servers ✅ Add rate limiting to prevent API abuse ✅ Use Zod schemas for type-safe tool definitions ✅ Test with MCP Inspector before deploying to production ✅ Update to SDK v1.20.2+ for security fixes ✅ Document all tools with clear descriptions ✅ Handle errors gracefully and return meaningful messages ✅ Use environment variables for secrets (never hardcode)

Never Do

❌ Export with object wrapper (
export default { fetch: app.fetch }
) ❌ Forget to close StreamableHTTPServerTransport ❌ Deploy without authentication in production ❌ Log environment variables or secrets ❌ Use CommonJS format (must use ES modules) ❌ Skip CORS configuration for browser clients ❌ Hardcode API keys or credentials ❌ Return raw error objects (may leak sensitive data) ❌ Deploy without testing tools/resources locally ❌ Use outdated SDK versions with known vulnerabilities

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: 
    npx @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