openapi-mcp-serverlisted

# openapi-mcp-server Turn a documented REST API into an MCP server agents can call safely. Spec first: MCP JSON Schema is the source of truth for messages (TypeScript schema + generated JSON Schema). ## Contract prep 1. OpenAPI 2.0 or 3.x, absolute base URL in `servers`, security schemes declared. 2. Fix common defects before codegen: duplicate `operationId`, missing path params, wrong types, dangling `$ref`. 3. Pick a dialect: JSON Schema 2020-12 is the MCP default when `$schema` is absent. 4. Auth stays in the host (bearer, OAuth 2.1, mTLS). Tokens never enter tool results or `_meta`. A clean contract usually yields working tools on the first pass; residual failures are often small schema bugs, not framework issues. ## Tool shape (do not mirror 1:1) Map **user goals**, not every endpoint: | Bad | Good | |---|---| | 80 REST verbs as tools | `search`, `get_project`, `update_project` | | One mega-tool with mode enum | One action per tool | Each tool needs: - Action-oriented `name` (prefer `camelCase` for tokenization). - `description` that says **when** to use it and one short example. - Explicit `inputSchema`; `outputSchema` when structured. - Accurate annotations: `readOnlyHint`, `destructiveHint`, `openWorldHint`. - Handler that authorizes, validates, and rate-limits. Annotations are hints. They never replace server-side authz. For research-style hosts, implement the standard read pair: - `search(query)` → `id`, `title`, `text`, `url` (canonical, citable). - `fe