Describe an existing API
Give an API you already run an MCP server, a CLI and a typed client, without writing a backend.
Your API might already exist, in another language or another service. Describe where each operation lives, and onedef calls it directly. There's no onedef server at all.
import { defineConfig, defineService, query, mutation } from 'onedef'
import { z } from 'zod'
export const config = defineConfig({
name: 'upstash',
baseUrl: 'https://api.upstash.com',
// HTTP Basic: account email + API key, read from these env vars by the CLI
auth: { basic: { userEnv: 'UPSTASH_EMAIL', passwordEnv: 'UPSTASH_API_KEY' } },
})
export const databases = defineService(config, {
name: 'databases',
description: 'Your Redis databases.',
ops: {
list: query({
summary: 'List databases',
output: z.array(Database),
http: { method: 'GET', path: '/v2/redis/databases', errors: { 401: 'UNAUTHORIZED' } },
}),
rename: mutation({
summary: 'Rename a database',
input: z.object({ id: z.string(), name: z.string() }),
http: { method: 'POST', path: '/v2/redis/rename/{id}', body: ({ input }) => ({ name: input.name }) },
}),
},
})An http descriptor says how to call one operation:
| field | what |
|---|---|
method, path | the route; {field} in the path is filled from the input |
query, headers, body | build them from the input (defaults: the rest of the input as body) |
select | map the upstream response onto your output schema |
errors | map upstream statuses onto your error codes, e.g. { 404: 'NOT_FOUND' } |
Then every surface uses the http() transport:
import { createClient, http } from 'onedef'
import { createMcpHandler, serveMcpStdio } from '@onedef/mcp'
import { runCli } from '@onedef/cli'
createClient(contract, http()) // a typed SDK
createMcpHandler(contract) // an MCP server (uses http() by default)
await runCli(contract, { transport: http() }) // a CLI with loginThe caller's credentials are forwarded to the API, so each user acts as themselves.
Mixing the two
Descriptors and handlers mix in one contract. An operation with a descriptor needs no handler, and a backend proxies the operations it doesn't implement. So you can move an API over one operation at a time.
The examples/upstash
example describes part of the Upstash API this way, and implements one operation itself.