Skip to Content
onedef

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.

contract.ts
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:

fieldwhat
method, paththe route; {field} in the path is filled from the input
query, headers, bodybuild them from the input (defaults: the rest of the input as body)
selectmap the upstream response onto your output schema
errorsmap 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 login

The 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.

On this page