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.
/plugin marketplace add secondsky/claude-skills/plugin install typescript-mcp@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/authentication-guide.mdreferences/cloudflare-agents-vs-standalone.mdreferences/cloudflare-integration.mdreferences/common-errors.mdreferences/deployment-guide.mdreferences/testing-guide.mdreferences/tool-patterns.mdscripts/init-mcp-server.shscripts/test-mcp-connection.shtemplates/authenticated-server.tstemplates/basic-mcp-server.tstemplates/full-server.tstemplates/resource-server.tstemplates/tool-server.tstemplates/wrangler.jsoncBuild 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.
Use this skill when:
Do NOT use this skill when:
MCP Protocol Components:
config://app, user://{userId})bun add @modelcontextprotocol/sdk hono zod
bun add -d @cloudflare/workers-types wrangler typescript
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;
wrangler deploy
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 configurationQuick 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.
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).
Quick Testing Workflow:
bunx @modelcontextprotocol/inspector# 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.
This skill prevents 13 documented errors. Here are the top 5 most critical:
Error: "Cannot read properties of undefined (reading 'map')"
Source: honojs/hono#3955
Prevention:
// ❌ WRONG // ✅ CORRECT
export default { fetch: app.fetch }; export default app;
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
});
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);
Error: Handler receives undefined arguments
Source: modelcontextprotocol/typescript-sdk#1026
Prevention: Use z.infer<typeof schema> for type-safe handler parameters
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.
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.
{
"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"
}
}
Use Cloudflare Agents MCP when you need:
Use this skill (standalone TypeScript MCP) when you need:
See references/cloudflare-agents-vs-standalone.md for detailed comparison.
Load reference files when working on specific aspects of TypeScript MCP servers:
Load when:
Load when:
Load when:
Load when:
Load when:
Load when:
Load when:
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 configurationReference 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 matrixScripts (scripts/): Automation tools
init-mcp-server.sh - Initialize new projecttest-mcp-connection.sh - Test server connectivity/websites/modelcontextprotocol (if available)Example Servers:
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
Use this checklist to verify your MCP server setup:
wrangler dev succeedsThis skill is based on patterns from:
Questions? Issues?
references/common-errors.md for troubleshootingbunx @modelcontextprotocol/inspectorLast Updated: 2025-10-28 SDK Version: @modelcontextprotocol/sdk@1.20.2 Maintainer: Claude Skills Repository
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.