opensourceagi/dev-tools-starter-agent/api2ai

Working With api2ai

Generates a production-ready MCP server from any OpenAPI spec, on top of mcp-use. Exact CLI flags, env vars, and generated file layout live in API.md.

Where the code is: packages/api2ai-mcp-generator in this repo holds the Next.js site/docs for the project — it has no bin entry and no generate-mcp-use-server.js. The generator itself is the published `api2ai` package, so npx api2ai … resolves from the registry, not from this folder. Don't go looking for the CLI source here.

Setup

npx api2ai https://petstore3.swagger.io/api/v3/openapi.json ./petstore-mcp --name petstore-api
cd petstore-mcp && npm install && npm start

Then open http://localhost:3000/inspector to exercise the tools.

The security model — read this before filing a bug

Three layers, and most "my tool is missing" reports are layer 1 or 2 working as designed:

1. Generation-time risk classification. Every operation is labeled and the label is baked into src/tools-config.js: low for GET/HEAD/OPTIONS, medium for any mutating method, high for anything matching admin/auth/billing/payments/tokens/secrets/user-management patterns. Only low is enabled by default. --allow-mutations promotes medium to enabled.
2. Runtime policy. checkToolPolicy() runs before every outbound call and reads env at call time — ALLOW_RESTRICTED_TOOLS=true unlocks medium/high, REQUIRE_APPROVALS=false drops the per-call approval gate. No regeneration needed.
3. HTTP hardening. Timeouts (REQUEST_TIMEOUT_MS, 30 s), a response cap (MAX_RESPONSE_BYTES, 10 MB), redirect: 'error', a host allowlist (ALLOWED_API_HOSTS), and credential-header protection — tool arguments can never override Authorization, Cookie, or X-API-Key; env-configured auth wins.

Picking the right filter

import { generateMcpServer, extractTools, loadOpenApiSpec } from "api2ai";
const result = await generateMcpServer(specUrl, "./out", {
  serverName: "my-api",
  allowMutations: false,
  includeTags: ["public"],
  filterFn: (tool) => tool.riskLevel === "low",
});

Connecting a client

Claude Desktop: {"mcpServers": {"my-api": {"url": "http://localhost:3000/mcp"}}}. The generated server also speaks the OpenAI Apps SDK, and exposes /sse and /health alongside /mcp and /inspector.

Troubleshooting