Review, wire up, and release the generated SDK, docs, and MCP server.

TypeScript SDK

A buildable npm package with typed request/response models, one resource class per tag, an SDK error hierarchy, and a default fetch-based transport.

MCP server

A Node.js MCP server exposing one tool per operation, classified by safety bucket, with input validation derived from the spec.

Documentation site

A self-contained static HTML site — browse it live at /projects/<slug>/docs or download the zip and host it on any static host (Vercel, Netlify, S3, GitHub Pages).

textmy-api-sdk/
  package.json          # name + version derived from your spec
  tsconfig.json
  README.md             # quickstart for the consumer
  src/
    index.ts            # exports the client and types
    client.ts           # PetstoreClient — accepts baseUrl + auth + fetch
    errors.ts           # typed SDK error classes
    types.ts            # every component schema as a typed interface
    resources/
      pets.ts           # one file per tag, methods grouped by operationId
      owners.ts

• Open the SDK preview and confirm resource grouping (one resource per tag) matches your mental model of the API.
• Open src/client.ts and verify the default baseUrl matches the environment you intend to publish for.
• Verify the auth scheme: bearer token, API key header, or query parameter. The generator picks it from the first security requirement on each operation.
• Scan resource files for any operation whose response shape is `unknown` — that indicates the spec used additionalProperties: true or returned a $ref we couldn&rsquo;t resolve.
• Build the package locally before publishing.

bashunzip my-api-typescript-sdk.zip -d my-api-sdk
cd my-api-sdk
npm install
npm run build
# inspect dist/ — should contain .d.ts files for every resource and type
npm pack

typescriptimport { PetstoreClient, PetstoreError } from "petstore-sdk";

const client = new PetstoreClient({
  baseUrl: process.env.PETSTORE_BASE_URL!,
  apiKey: process.env.PETSTORE_API_KEY!,
  // Optional: bring your own fetch (e.g. for tracing or proxying)
  fetch: globalThis.fetch.bind(globalThis),
});

try {
  const pets = await client.pets.list({ limit: 50 });
  for (const pet of pets.items) {
    console.log(pet.id, pet.name);
  }
} catch (err) {
  if (err instanceof PetstoreError) {
    // err.status, err.code, err.message — all typed
    console.error("API failure", err.status, err.code);
  } else {
    throw err;
  }
}

textmy-api-mcp/
  package.json          # depends on @modelcontextprotocol/server (MCP SDK v2), Node 22+
  README.md             # client wiring snippets (Claude Desktop, Claude Code, Cursor, etc.)
  src/
    server.ts           # MCP entry point: stdio, or stateless HTTP with MCP_TRANSPORT=http
    tools.ts            # one tool per operation: JSON Schema in/out, annotations, safety
    http-client.ts      # generated HTTP client (separate from the SDK package)
    env.ts              # required env vars: API_BASE_URL, auth credential names
    args.ts             # routes validated arguments to path / query / header / body

Every tool is bucketed automatically. The MCP preview surfaces the counts so you can spot-check before release.

safe

Read-only GET / HEAD on non-administrative paths, or operations marked x-mcp-safe: true. Advertised with readOnlyHint.

destructive

Any other mutation (POST / PUT / PATCH / DELETE), or a destructive verb like delete, cancel or revoke in the operation name. Off unless enabled.

admin

Paths that touch administrative surface (users, roles, billing, keys, tokens, settings, webhooks). Off unless enabled separately.

disabled

Operations marked x-mcp-disabled: true or x-dangerous: true, and deprecated operations. Never registered as tools.

• Open the MCP preview and walk through every tool in the `destructive` and `admin` buckets. Confirm each one belongs there.
• Decide which buckets to enable in your runtime: most teams ship with `safe` only, and require explicit opt-in for the others.
• Provide least-privilege credentials. Do not reuse a token that can also reach unrelated systems.
• Configure logging in the host runtime so agent invocations are auditable.
• Pin the spec revision and the generated package version in your runbook so re-issuing a server is reproducible.

bashunzip my-api-mcp-server.zip -d my-api-mcp
cd my-api-mcp
npm install
export API_BASE_URL="https://api.example.com"
export API_KEY="sk_…"
# Enable only the safe bucket initially
export MCP_ENABLED_BUCKETS="safe"
npm run start

Register the server as an MCP stdio command in the host client. The exact snippet is included in the generated README.md. A typical Claude Desktop config:

json{
  "mcpServers": {
    "petstore": {
      "command": "node",
      "args": ["/absolute/path/to/my-api-mcp/dist/server.js"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "API_KEY": "sk_…",
        "MCP_ENABLED_BUCKETS": "safe"
      }
    }
  }
}

• Keep docs, SDK, and MCP releases tied to the same source spec revision. Track the SHA in the release notes for the consuming repo.
• Treat any change to a tool&rsquo;s safety bucket as a security-relevant event. Require a second reviewer.
• Add rollout gates for breaking API changes — downstream agents should not silently start invoking renamed tools.
• Run the regenerate flow after every spec change. Hand-patching generated files is not supported.
• Subscribe maintainers to the spec source so they hear about destructive-method additions before they appear in a release.

SDK methods named odd things

Add operationId to the spec — without it, Ajolla synthesizes method names from method + path.

MCP tool input is `any`

Replace inline objects with named components or remove additionalProperties: true. Both weaken input validation.

Auth not flowing through

Confirm the operation references the right securityScheme. Operations without security: [] inherit the document-level requirement.

Generation succeeded but the SDK, docs, or MCP zip 404s

Signed download URLs expire after 60 seconds. Click Download zip again to mint a fresh URL.

Destructive operation marked safe

Add x-ajolla-safety: destructive to the operation. The default classification is method-based and can&rsquo;t see business semantics.

• Getting started — Sign in to first generated zip in one session.
• OpenAPI readiness — Make the inputs better so these checklists get shorter.
• Using the CLI — Trigger regenerations and pull artifacts from CI.