Ts Template MCP server

@cyanheads/mcp-ts-core Agent-native TypeScript framework for building MCP servers. Runtime infrastructure for your server, and the agent skills to build, test, and ship it.

Quick start · Capabilities · API reference · Examples

Build AI tools for anything you can describe

Connect an API, a dataset, or a workflow to an AI agent through the Model Context Protocol (MCP). Your project holds the domain code; @cyanheads/mcp-ts-core handles the auth, storage, logging, and transports underneath it.

Agent-native. Every scaffold ships the framework reference and a set of Agent Skills: workflows for designing tools, writing tests, reviewing security, and cutting releases. You decide what the server does; your agent follows the skills to build it.

The framework stays a dependency. Infrastructure fixes arrive as package upgrades. Run the maintenance skill and your agent bumps core, syncs the latest skills, and adopts what changed.

Quick start

Servers run on Bun, Node.js 24+, or Cloudflare Workers.

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

The scaffold includes a source tree, build and test configuration, CLAUDE.md/AGENTS.md, Agent Skills, and plugin metadata for Claude Code and Codex. Open it in Claude Code, Codex, or another agent and describe what you want:

Build an MCP server for my team's inventory API. We need to find products, check stock across warehouses, investigate stock movements, and record adjustments and transfers. Let's get started.

Already have a TypeScript project? Run bun add @cyanheads/mcp-ts-core and register your definitions with createApp().

A tool is a schema and a function

This is a complete server that searches a three-item catalog. To try it, replace the scaffold's src/index.ts with it:

import { createApp, tool, z } from '@cyanheads/mcp-ts-core';

const catalog = ['Notebook', 'Mechanical pencil', 'Desk lamp'];

const search = tool('catalog_search', {
  description: 'Search catalog item names. An empty query lists all items.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Text to find in an item name'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names'),
  }),
  async handler({ query }) {
    return {
      items: catalog.filter((name) =>
        name.toLowerCase().includes(query.toLowerCase()),
      ),
    };
  },
});

await createApp({ name: 'catalog-mcp-server', title: 'catalog-mcp-server', tools: [search] });

Build and run it over HTTP:

bun run rebuild
bun run start:http

Point your MCP client at http://127.0.0.1:3010/mcp (Streamable HTTP), or have the client launch it over stdio with bun /absolute/path/to/dist/index.js.

What comes with it

Shortened. The full README is on GitHub.