mcp-ts-core

What it does

@cyanheads/mcp-ts-core is the infrastructure layer for TypeScript MCP servers. Instead of rebuilding transports, auth, logging, and storage in every project, you install this as a dependency and focus entirely on writing tools, resources, and prompts. Declarative builders handle registration, validation, and response formatting. Supports both Node.js (stdio and HTTP via Hono) and Cloudflare Workers with the same definitions.

Key features

• Declarative builders — tool(), resource(), prompt() with Zod schemas; the framework handles validation and MCP response formatting automatically
• Unified Context — handlers receive ctx.log (request-scoped), ctx.state (tenant storage), ctx.elicit (user prompting), ctx.sample (LLM completion), ctx.signal (cancellation)
• Inline auth — add auth: ['scope'] to any definition; framework checks before calling your handler
• Task tools — task: true flag for long-running operations with built-in lifecycle management and progress reporting
• Multi-backend storage — swap between in-memory, filesystem, Supabase, or Cloudflare D1/KV/R2 via env var
• OpenTelemetry — structured Pino logging with optional trace/metrics export; every tool call auto-instrumented
• Definition linter — validateDefinitions() checks tools/resources/prompts against MCP spec at startup
• Edge-ready — createWorkerHandler() for Cloudflare Workers; same code, different entry point

Installation

Claude Desktop — after scaffolding a server with the framework, add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio" }
    }
  }
}

Scaffold a new server:

bunx @cyanheads/mcp-ts-core init my-mcp-server
cd my-mcp-server && bun install

VS Code Copilot — add built server to .vscode/settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/dist/index.js"]
    }
  }
}

Supported hosts

Works with any MCP client; confirmed usage with Claude Desktop and VS Code Copilot in official documentation.