undefined

```ts
// scripts/load-spec.ts (run once, manually or as a build step)
import SwaggerParser from "@apidevtools/swagger-parser";
import { writeFileSync } from "node:fs";

const spec = await SwaggerParser.dereference("./openapi.yaml");
writeFileSync("./openapi.dereferenced.json", JSON.stringify(spec, null, 2));

undefined

Let the scaffold install dependencies and `git init` — both are useful (`npm install` runs `mcp-use generate-types` postinstall, and a git repo is required by `npm run deploy` later). The skill installs companion coding-agent skills by default too; that's fine.

Verify the template catalog with `npx create-mcp-use-app@latest --list-templates` if it's been a while — the available set is `blank`, `starter`, `mcp-apps` as of this writing. `starter` includes sample tools you'd rip out, so we don't recommend it here.

After scaffolding, add the two extra deps the OpenAPI flow needs:

```bash
cd <project-name>
npm install @apidevtools/swagger-parser dotenv

<project>/
├── index.ts                         # MCPServer + server.tool() registration loop
├── openapi.yaml                     # The original spec (committed)
├── openapi.dereferenced.json        # Dereferenced spec (gitignored; regenerated)
├── src/
│   ├── client.ts                    # fetch-based HTTP client (base URL + auth + error handling)
│   ├── auth.ts                      # Reads env vars, builds the auth header
│   ├── operations.ts                # Loads dereferenced spec, exposes operation metadata
│   └── schema.ts                    # OpenAPI schema → zod converter
├── scripts/
│   └── load-spec.ts                 # Dereference helper (step 2)
├── .env.example                     # Document required env vars (API_KEY, BASE_URL, etc.)
└── package.json

import "dotenv/config";
import { MCPServer, text } from "mcp-use/server";
import { operations } from "./src/operations";
import { callOperation } from "./src/client";
import { operationToZod } from "./src/schema";

// Keep the MCPServer fields the scaffold gave you (title, baseUrl, favicon, icons).
// Just adjust `name`, `title`, and `description` to match the API you're wrapping.
const server = new MCPServer({
  name: "<api-name>",
  title: "<API name>",
  version: "1.0.0",
  description: "MCP server wrapping the <API name> REST API",
  baseUrl: process.env.MCP_URL || "http://localhost:3000",
  favicon: "favicon.ico",
  icons: [{ src: "icon.svg", mimeType: "image/svg+xml", sizes: ["512x512"] }],
});

for (const op of operations) {
  server.tool(
    {
      name: op.toolName,
      description: op.description,
      schema: operationToZod(op),
    },
    async (args) => {
      const result = await callOperation(op.operationId, args);
      return text(typeof result === "string" ? result : JSON.stringify(result, null, 2));
    },
  );
}

// Streamable HTTP transport — the only supported transport for this skill.
// MCP endpoint: POST http://localhost:<port>/mcp
// Inspector:    http://localhost:<port>/inspector
const PORT = process.env.PORT ? Number(process.env.PORT) : 3000;
server.listen(PORT);

npm run dev

undefined

For CI / scripted tests, add `--json` and pipe to `jq`. If `tools list` returns nothing, your operation filter in `index.ts` killed everything or `openapi.dereferenced.json` is missing. If `connect` itself fails, the dev server isn't running or it's on a different port — drop to curl (see `references/testing.md` section "Raw protocol debugging") to confirm the endpoint is alive at all.

**Layer 2 — Inspector chat (the real LLM loop).** Layer 1 proves the server works. The inspector proves the **LLM can use it** — that the tool description is descriptive enough for the model to pick the right tool, that the zod schema has enough hints to fill args correctly, that the response shape isn't so weird the model can't summarize it.

Test both force-invocation ("Use `list_pets` with limit 5.") and free-form discovery ("Show me the first 5 pets in the store.") — the second is harder and the one that catches description quality.

Test the failure paths in both layers: missing required arg (zod rejection), wrong auth (upstream 401), upstream 5xx (point `BASE_URL` at a dead port). Both layers should degrade with a clean error, not a server crash.

If you see "Failed to resolve import" or stale tool definitions in either layer: `rm -rf .mcp-use && npm run dev`.

npx mcp-use login
npm run deploy

gh repo create <org>/<name> --private --source=. --push