OpenAPI to TypeScript: Generate Typed Clients in 30 Seconds

If you've ever integrated against a REST API from a TypeScript codebase, you know the drill. You read the OpenAPI spec, hand-write interfaces for the request body and response, miss a nullable field, ship a bug, and find it at 2am when production returns a shape you didn't expect. The next week the API adds a field, nobody remembers to update your types, and the whole cycle repeats.

There's a better way. Your OpenAPI spec already describes every request, response, and error shape. The job of turning that spec into TypeScript types should be automatic — and ideally it should stay accurate as the API drifts.

This guide covers three approaches: the classic CLI codegen route, the modern MCP-powered approach, and a hybrid for teams that want both developer ergonomics and compile-time guarantees.

The classic way: codegen CLIs

Tools like openapi-typescript and orval read a spec URL and spit out a .d.ts file full of interfaces. The workflow looks like this:

# Install
npm install -D openapi-typescript

# Generate
npx openapi-typescript https://api.example.com/openapi.json \
  --output src/types/api.d.ts

It works, but it's a lot of ceremony. You have to check the generated file into git, remember to re-run when the spec changes, handle failures in CI, and deal with the fact that different codegen tools emit subtly different type shapes.

The bigger problem: what if your OpenAPI spec is incomplete? Many APIs (especially ones generated from FastAPI, Django REST Framework, or Express) ship specs that list endpoints but leave response schemas half-defined. You run codegen, you get unknown for every response body, and you're back to hand-typing.

The MCP way: generate types on demand, from real data

Outworx Docs ships a per-project Model Context Protocol server. Your API already has docs hosted at yourslug.docs.outworx.io; the MCP endpoint at docs.outworx.io/api/mcp/yourslug exposes 12 tools that AI assistants like Claude Desktop and Cursor can call — including generate_types.

From inside Cursor, you can literally ask:

"Generate TypeScript types for the listPosts endpoint."

Cursor calls generate_types with scope="endpoint", gets back a self-contained TypeScript module, and drops it into your codebase. Under the hood, Outworx:

• Parses your hosted spec into a normalized internal model
• Renders every named schema as an export interface
• Emits per-endpoint OpNameRequest, OpNameResponse, OpNameError aliases
• Caches the result so the next caller gets it instantly

Here's what you get back:

// Types for listPosts — GET /api/feed/posts
export interface ListPostsQueryParams {
  /** Page number (1-indexed) */
  page?: number;
  /** Results per page */
  limit?: number;
}

/** 200 — Page of posts */
export type ListPostsResponse = {
  items: Post[];
  total: number;
  page: number;
};

/** 401 — Unauthorized */
export type ListPostsError401 = {
  error: string;
  code: string;
};

Self-healing types: the killer move

Here's the part no CLI codegen tool can do. When an MCP client calls execute_endpoint with real credentials, Outworx captures the response body and merges it into an inferred schema stored per (version, endpoint, status). Over multiple samples from multiple users, the stored schema converges on the real contract — including fields the OpenAPI spec never documented.

The next generate_types call for that endpoint uses the inferred schema as a fallback, so generated TypeScript reflects actual API behavior even when the spec is incomplete. And because every live call re-validates, drift (new fields, type changes) is caught immediately and the cached types are regenerated.

This is particularly powerful for APIs that were specced after the fact, or for community-driven APIs where the spec trails the implementation. The types improve as people use them.

Hybrid approach: cache locally, regenerate on change

For production TypeScript monorepos, you still want types checked into git for offline builds and deterministic CI. The MCP flow dovetails with that:

1. Ask your AI assistant to generate types for the endpoints you actually use — not the whole spec
2. Paste into src/types/api.ts (or a dedicated @company/api-types package)
3. When the AI hits your API via execute_endpoint later and detects drift, it prompts you to regenerate

You get the ergonomic benefit of on-demand generation plus the audit-friendly behavior of checked-in types. Best of both worlds.

Try it

If you already host your API docs on Outworx, open the MCP tab on your project, copy the Cursor or Claude Desktop snippet, paste it into your MCP config, and ask your AI assistant to generate types for any endpoint. The whole loop takes about 30 seconds.

If you don't host your docs with us yet — that's the next 30 seconds. Upload your OpenAPI spec, get a hosted URL, and the MCP endpoint comes free on Pro and Business plans.