MCP + OpenAPI TypeScript stack (library-first)

For the generated REST client and any hand-written fetch layer in this pattern, use ky via @hey-api/client-ky. Do not use axios — avoid @hey-api/client-axios, axios interceptors, or axios examples when implementing or regenerating clients for MCP servers in this stack. Ky fits Request/Response, keeps a small surface, and matches the interceptor style used for per-request / multi-tenant auth.

@hey-api/openapi-ts (essentials)

What it is: @hey-api/openapi-ts is the CLI and defineConfig() entrypoint that generates client.gen.ts (Ky), sdk.gen.ts (per-operation functions), types, and optional Zod request schemas (zod.gen.ts) from OpenAPI 3.x.

Run codegen from the repo root (after input spec is valid):

bunx openapi-ts
# or: npx @hey-api/openapi-ts

Typical openapi-ts.config.ts plugin chain for this stack: @hey-api/client-ky (with baseUrl) → @hey-api/schemas → @hey-api/transformers → @hey-api/typescript → @hey-api/sdk with validator: { request: "zod" } so MCP atomic tools can reuse generated Zod for tool inputSchema. Plugin order matters; the legacy plugin name @hey-api/services is now @hey-api/sdk (output sdk.gen.ts, not services.gen.ts).

Authoritative detail (CLI flags, all plugins, migrations, Valibot): see reference/openapi-ts.md and the upstream hey-api/openapi-ts docs.

Discovery questions (ask before planning or implementing)

Answer these for any MCP server so the layout stays appropriate:

1. Tenancy / credentials

   • Single-tenant only (one API key or token per process)?
   • Multi-tenant HTTP (per-request key, token, or async resolver)?
   • Both (e.g. stdio + shared secret for local dev; HTTP + per-tenant for hosted)?

2. Transports

   • stdio only (local MCP clients)?
   • Streamable HTTP only (remote gateway)?
   • Both (same tool registration; different connect paths)?

3. Deployment target

   • Long-lived process (Node / Bun on a VM or container)?
   • Edge runtime (Cloudflare Workers, Deno Deploy, Vercel Edge)?
   • Edge runtimes impose startup CPU limits (e.g. Workers: ~50 ms CPU). Generated Zod schemas (zod.gen.ts) can be thousands of lines; static imports cause all schemas to evaluate at startup, exceeding the budget. Plan for deferred module loading (see reference/structure-and-flows.md).

4. Distribution shape

   • CLI-only binary (users run a command)?
   • Library-only (embed create*McpServer in another app)?
   • Both (recommended: package.json exports + bin)?

5. API surface

   • Is there a machine-readable OpenAPI spec (or can you maintain one)?
   • If not, you can still use the same folder ideas (hand-written client + Zod), but you lose one spec as source of truth for request shapes.

6. Workflow vs atomic tools

   • Start 1:1 with endpoints (mcp-builder bias), then add workflows (mcp-workflow-design). A common split: atomic tools under src/tools/<domain>.ts (or similar) and composite tools under src/tools/workflows/.

7. Upstream authentication schemes

   • Does the API support HTTP Basic (including “two-part” secrets encoded as Basic per vendor docs), Bearer (OAuth or PAT), both, or other schemes (API-key headers, mTLS)?
   • For OAuth: who obtains and refreshes tokens — the MCP process, a gateway in front of MCP, or an external secret/token service the resolver calls?

Optional follow-ups: Node vs Bun for the default HTTP entrypoint, rate limits, and whether tenant secrets may appear in process memory (TLS, resolver to KMS/DB, etc.).

Authentication

Upstream REST APIs often document multiple valid ways to authenticate. The MCP layer should model which modes you support in this package (documented in README / env), and map each mode to one outbound Authorization (or custom) header on the shared HTTP client — via default config, per-request ALS + interceptor, or both.

Scheme families to plan for

1. HTTP Basic with a derived token (two-part secrets) Some vendors issue an access key (or ID) and a separate secret. The wire format is still RFC 7617 Basic: concatenate with a colon, Base64-encode the UTF-8 string, send:

Authorization: Basic <Base64(accessKey + ":" + accessKeySecret)>

Operators may create this once in a shell or your CLI reads two env vars and builds the header at startup. Do not confuse this with “username only” Basic (some APIs use empty password).

2. Bearer token (OAuth or non-OAuth PAT) After the user or system obtains a token (OAuth flow, developer portal, etc.),