mcp-ts-core

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

Optional integrations (DuckDB, Supabase, the OpenTelemetry SDK) are peer dependencies; install them when you need them.

Give agents useful results

Two declared contracts shape what an agent gets back. enrichment carries success-path context (totals, the parsed query, empty-result notices), populated with ctx.enrich(). errors lists each expected failure with its recovery guidance, and the handler throws one with the typed ctx.fail().

runSearch(query, limit) stands in for your search backend. It returns { items, total, parsed }, or null when the index is down:

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

const search = tool('search', {
  description: 'Search the catalog and return ranked matches.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Search terms'),
    limit: z.number().int().min(1).default(10).describe('Max results'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names, best first'),
  }),
  enrichment: {
    effectiveQuery: z.string().describe('Query as the server parsed it'),
    totalCount: z.number().describe('Total matches before the limit'),
    notice: z.string().optional().describe('Guidance when nothing matched'),
  },
  errors: [
    {
      reason: 'index_unavailable',
      code: JsonRpcErrorCode.ServiceUnavailable,
      when: 'The upstream search index is unreachable.',
      retryable: true,
      recovery: 'Retry in a few seconds — the index may be briefly unavailable.',
    },
  ],
  handler: async (input, ctx) => {
    const res = await runSearch(input.query, input.limit);
    if (!res) throw ctx.fail('index_unavailable');
    ctx.enrich({ effectiveQuery: res.parsed, totalCount: res.total });
    if (res.items.length === 0) {
      ctx.enrich({ notice: `No matches for "${input.query}". Try broader terms.` });
    }
    return { items: res.items }; // enrichment never rides in the domain return
  },
});

await createApp({ tools: [search] });

Both contracts are advertised in tools/list, so clients see them before calling, and the definition linter checks the handler against them. A failure with a declared reason reaches the client carrying that entry's recovery hint, and every tool error carries the request ID its server log records share.

Same data across client surfaces

MCP hosts differ in which part of a tool result they hand the agent: structuredContent (JSON), content[] (text), or both. The framework fills both with the same data, so the agent sees the same result on any host.

format() renders the text side; without one, content[] gets JSON. The format-parity lint rule fails lint:mcp if any output field is missing from the rendered text. Enrichment needs no format() entry, because the framework adds it to both surfaces. This formatter renders the items as a markdown list:

format: (result) => [{
  type: 'text',
  text: result.items.length > 0
    ? result.items.map((name) => `- ${name}`).join('\n')
    : 'No matching items.',
}],

Resources

Resources expose data at a URI. This one reads from your own getItem() service:

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

export const itemData = resource('items://{itemId}', {
  description: 'Retrieve item data by ID.',
  params: z.object({
    itemId: z.string().describe('Item ID'),
  }),
  async handler(params) {
    return await getItem(params.itemId);
  },
});

Everything registers through createApp() in your entry point:

await createApp({
  name: 'my-mcp-server',
  title: 'my-mcp-server', // display name in client UIs
  tools: allToolDefinitions,
  resources: allResourceDefinitions,
  prompts: allPromptDefinitions,
  instructions: 'Brief composition hints for the model.', // optional, sent on every `initialize`
  skills: 'skills', // optional, serves root skills/ over the SEP-2640 Skills extension
});

On Cloudflare Workers, createWorkerHandler() takes the same definitions from a separate entry point.

Runtime and integration details

• Auth and storage: Declare auth: ['scope'] on a definition and the scope is checked, under JWT or OAuth, before the handler runs. ctx.state is tenant-scoped storage over in-memory, filesystem, Supabase, or Cloudflare D1/KV/R2, chosen by config.
• Client interaction: Return ctx.requestInput(...) to ask the user for input, the client's model for a sample, or the client for its roots. The handler runs again with the answers on ctx.inputs.
• Protocol compatibility: HTTP serves 2026-07-28 clients (per-request _meta envelope) and session-based 2025-era clients. The SDK's compatibility layer handles input requests for the older ones.
• Server presentation: instructions gives the model server-wide guidance once, at initialize, instead of in every tool description. Identity fields (title, websiteUrl, description, icons) populate the client's server info, the /.well-known/mcp.json server card, and the HTTP landing page. skills: 'skills' serves the Agent Skills the server publishes in root skills/ through the SEP-2640 Skills extension (skills/list, skills/get), checked at build time by lint:packaging.
• Definition checks: lint:mcp checks names, schemas, scopes, annotations, format parity, and JSON Schema portability. It runs at build time, never at startup, so a new rule can't break a deployed server.
• DataCanvas: An optional DuckDB workspace where agents run SQL across