Getting started

stitchkit turns one contract into an HTTP API, MCP tools, AI-agent tools and a typed client. This page gets a working app running; the rest of the guide goes deep on each piece.

Requirements

• Bun >= 1.2 (recommended) or Node.js >= 22. Bun is first-class; Node is supported via stitchkit/node.

Install

bun add stitchkit zod

zod is a required peer — schemas are the source of truth everywhere. Other peers are optional and pulled in only when you use the matching feature (@modelcontextprotocol/server for MCP servers, ai for agents, socket.io* for realtime, @tanstack/react-query + react-query-kit for React). See deps below.

Entrypoints

Every entrypoint is import-safe for one environment — keeping server-only code (Bun.serve, the MCP SDK) out of browser bundles.

Each also declares how settled it is. Stable means the shape changes rarely and only with a reason worth a migration. Evolving means the shape is still being found and may be redefined in any minor — always with a ### ⚠️ Breaking changes entry and a migration section, never silently. Both are legitimate choices; the difference is how often you should expect to read the changelog. Moving an entrypoint from evolving to stable is a decision on its own, recorded as an ADR.

Rule of thumb: browser code imports stitchkit and stitchkit/react; server code adds stitchkit/server (or stitchkit/node on Node) and opts into stitchkit/tools, stitchkit/remote or stitchkit/files by capability. The full export list of each is in the API reference.

Project layout

A contract is shared by both sides, so it lives in its own folder:

src/
├── shared/contracts.ts   the contract — imported by server and client
├── server/index.ts       implement() + createServer()
└── client/api.ts         createClient()

A first app

1. Define the contract

// src/shared/contracts.ts
import { defineContract } from 'stitchkit'
import { z } from 'zod'

const Note = z.object({ id: z.string(), text: z.string() })

export const notes = defineContract({ prefix: 'notes' }, {
  list:   { method: 'GET',  path: '/',    desc: 'List notes',  output: z.array(Note) },
  create: { method: 'POST', path: '/',    desc: 'Create note', input: z.object({ text: z.string() }), output: Note },
  get:    { method: 'GET',  path: '/:id', desc: 'Get a note',  params: z.object({ id: z.string() }), output: Note },
})

2. Implement and serve

// src/server/index.ts
import { implement, createServer } from 'stitchkit/server'
import { notes } from '../shared/contracts'

const service = implement(notes, {
  list:   ()    => db.list(),
  create: (ctx) => db.create(ctx.input.text),   // ctx.input is typed
  get:    (ctx) => db.get(ctx.params.id),       // ctx.params is typed
})

createServer({ services: [service], port: 3000 })

3. Call it, typed

// src/client/api.ts
import { createClient, createHttpClient } from 'stitchkit'
import { notes } from '../shared/contracts'

export const api = createClient(notes, createHttpClient({ baseUrl: '/api' }))

await api.list()                   // GET  /notes      → Note[]
await api.create({ text: 'hi' })   // POST /notes      → Note
await api.get({ id: '1' })         // GET  /notes/1    → Note

Run the server with bun run src/server/index.ts. The contract is the single source of truth — change it and both the handler and the client are re-typed at once.

On Node

createServer is Bun’s Bun.serve. On Node ≥ 22, swap it for serveNode (from stitchkit/node, built on srvx) — the contract, implement and the client are identical:

import { serveNode } from 'stitchkit/node'

serveNode({ services: [service], port: 3000 })

Add @types/bun as a dev dependency on Node (an optional peer — it types the shared stitchkit/server surface). See deployment.

Dependencies

ky is the only bundled runtime dependency. Everything else is an optional peer — your app installs only what the features it uses need, and owns the version (one shared instance, no dual-version skew). This matrix is the install map — feature → packages:

bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun

Dynamic optional-peer adapters fail with an actionable error naming the package and install command. Static entrypoints such as stitchkit/tools fail during ESM resolution by naming the exact missing package; the feature-to-peer matrix below is the canonical install command.

The combined tools entry owns MCP and AI-agent adapters, so install both runtime peers before importing stitchkit/tools:

bun add @modelcontextprotocol/server@^2 ai@^7

Browser, HTTP-client and React entrypoints remain usable without either MCP package. MCP hosts and client E2E additionally install @modelcontextprotocol/client@^2; Apps additionally install @modelcontextprotocol/ext-apps.

Next

• Contracts — every endpoint field, in depth.
• HTTP server — createServer, hooks, raw routes, primitives.
• Typed client — the client, React data layer, SSE.
• MCP & agents — contracts as AI tools.
• Realtime — Socket.IO and the cache bridge.
• Auth & errors — scopes, auth hooks, the error model.
• Browser OAuth and Google OIDC — PKCE transaction and verified provider identity.
• Testing & deployment.
• API reference — every export, by entrypoint.

For a complete production-shaped app, run bun create stitchkit my-app. The canonical generated topology is maintained in packages/create-stitchkit/template.

For a terminal Agent host instead, run bun create stitchkit my-agent --template agent, copy .env.example to .env, set OPENROUTER_API_KEY, then run bun run dev and choose a live tool-capable model with /model. The provider catalog owns the exact model id and context window and presents weekly popularity separately from sourced benchmark observations; OPENROUTER_MODEL is only an optional preferred row. That profile is a thin stitchkit.agent.ts composition over the official stitchkit-tui package and canonical headless harness: durable SQLite history, lazy skills, direct coding tools, approval continuations and recovery stay framework-owned primitives, while model choice, permissions, executables and OS isolation remain application policy.