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.
bash
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:
ts
import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
const catalog = ['Notebook', 'Mechanical pencil', 'Desk lamp'];
const search = tool('catalogsearch', {
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:
bash
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
| You need to… | The framework provides |
| Give an assistant useful capabilities | Typed builders for tools, resources, prompts, and interactive MCP Apps |
| Help an agent use those capabilities correctly | Server instructions, result enrichment, and declared errors with recovery guidance |
| Control access and keep state | JWT/OAuth, per-definition scopes, and tenant-scoped storage with swappable backends |
| Run locally or host a service | stdio and HTTP on Bun/Node.js; a separate entry point for Cloudflare Workers |