Skip to Content
onedef

Quick start

A notes API with REST, OpenAPI and an MCP server, in a Next.js app.

You'll build a small notes API and get, without writing any of it by hand:

  • REST endpoints and an OpenAPI document,
  • an MCP server that Claude Code can use,
  • a typed client for your pages.

The finished code is examples/quickstart in the repository.

Install

In a Next.js app (App Router):

pnpm add onedef @onedef/orpc @onedef/mcp @modelcontextprotocol/server zod

Describe the API: lib/contract.ts

The contract says what your API is. It has no server code, so any client can import it.

lib/contract.ts
import { action, collection, defineApi, defineConfig } from 'onedef'
import { z } from 'zod'

export const config = defineConfig({ name: 'notes', description: 'A tiny notes API.' })

const Note = z.object({
  id: z.string(),
  title: z.string(),
  done: z.boolean(),
})

export const notes = collection(config, {
  name: 'notes',
  description: 'Your notes.',
  id: 'id',
  fields: Note,
  create: { input: z.object({ title: z.string().describe('What to remember') }) },
  actions: {
    complete: action({ summary: 'Mark a note as done', output: Note, needs: 'object' }),
  },
})

export const contract = defineApi(config, { notes })

A collection always has list and get. Here it also has create, and one action of your own, complete. needs: 'object' means the handler receives the note, already loaded.

Implement it: lib/backend.ts

One handler per operation. TypeScript checks every one against the contract.

lib/backend.ts
import { fail, implement } from 'onedef'
import { contract } from './contract'

// A Map stands in for your database.
const db = new Map<string, { id: string; title: string; done: boolean }>()

export const backend = implement(contract, {
  notes: {
    list: () => [...db.values()],
    get: ({ id }) => db.get(id) ?? fail('NOT_FOUND', `No note "${id}"`),
    create: ({ input }) => {
      const note = { id: crypto.randomUUID(), title: input.title, done: false }
      db.set(note.id, note)
      return note
    },
    complete: ({ object }) => {
      const note = { ...object, done: true }
      db.set(note.id, note)
      return note
    },
  },
})

Try deleting the complete handler: the file stops compiling.

Serve it: two route files

app/api/[[...route]]/route.ts
// REST, RPC and the OpenAPI document, under /api
import { toNextHandlers } from '@onedef/orpc'
import { backend } from '@/lib/backend'

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = toNextHandlers(backend)
app/mcp/route.ts
// The MCP server, at /mcp
import { createMcpHandler } from '@onedef/mcp'
import { backend } from '@/lib/backend'

const handler = createMcpHandler(backend)
export { handler as GET, handler as POST, handler as DELETE }

Try it

Run pnpm dev, then:

curl -X POST localhost:3000/api/notes -H 'content-type: application/json' -d '{"title":"Buy milk"}'
curl localhost:3000/api/notes
curl localhost:3000/api/openapi.json

Connect Claude Code to the MCP server, and ask for something in plain words:

claude mcp add --transport http notes http://localhost:3000/mcp
> Add a note titled "Call mom", mark it as done, then list my notes.

Claude finds notes_create, notes_complete and notes_list on its own. Their descriptions come from your contract.

Use it from a page

The typed client calls the same API, with the contract's types:

app/page.tsx
'use client'
import { rpc } from '@onedef/orpc/client'
import { createClient } from 'onedef'
import { useEffect, useState } from 'react'
import { contract } from '@/lib/contract'

const api = createClient(contract, rpc({ url: '/api' }))

export default function Home() {
  const [notes, setNotes] = useState<Awaited<ReturnType<typeof api.notes.list>>>([])
  useEffect(() => {
    api.notes.list().then(setNotes)
  }, [])
  return <ul>{notes.map((note) => <li key={note.id}>{note.title}</li>)}</ul>
}

note.title is typed, and so is every input. Rename a field in the contract, and this page stops compiling until it's fixed.

Next

On this page