# Mcp Openapi

> OpenAPI 3.x to MCP server bridge in TypeScript with stdio, StreamableHTTP, and SSE transports

- **Type:** MCP server
- **Install:** `agentstack add mcp-evalops-mcp-openapi`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [evalops](https://agentstack.voostack.com/s/evalops)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [evalops](https://github.com/evalops)
- **Source:** https://github.com/evalops/mcp-openapi

## Install

```sh
agentstack add mcp-evalops-mcp-openapi
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-openapi

OpenAPI 3.x to MCP server bridge in TypeScript.

`mcp-openapi` takes an OpenAPI spec and turns it into an MCP server where each OpenAPI operation is an MCP tool. Tool calls are proxied to the original REST API with runtime validation and auth handling.

## Capabilities

- OpenAPI 3.0+ support (YAML/JSON, `$ref` dereference, operation compilation)
- Proxy behavior to upstream REST API
- Authentication via env vars:
  - API keys (`in: header|query|cookie`)
  - HTTP Bearer
  - HTTP Basic
  - OAuth2 / OpenID Connect (static token or client credentials token fetch)
- Runtime validation:
  - Zod validation generated from OpenAPI-derived JSON Schema
  - AJV JSON Schema validation
  - Response schema validation by HTTP status
- Typed TypeScript implementation
- Strict lint mode for OpenAPI quality gates (`--strict`)
- Configurable tool naming template (`--tool-name-template`)
- Policy engine:
  - allow/deny tool patterns
  - allow methods/path prefixes
  - allow hosts
- Optional response transform hook (`--response-transform `)
- Multiple transports:
  - `stdio`
  - `streamable-http` (Hono)
  - `sse` (legacy compatibility transport)
- Transport hardening:
  - graceful shutdown
  - SSE session caps/TTL
- Observability:
  - Prometheus metrics
  - status counters
  - latency histogram buckets
- Built-in browser test clients:
  - `/test/streamable`
  - `/test/sse`
- Project scaffold (`init`) that generates:
  - `package.json`
  - `tsconfig.json`
  - `src/server.ts`
  - `.env.example`
  - `README.md`
  - `Dockerfile`

## Install

```bash
npm install
```

Consume as a library from GitHub:

```bash
npm install github:evalops/mcp-openapi
```

## Library Usage

```ts
import { parseSpec, generateToolsWithTags } from "mcp-openapi";

const normalized = await parseSpec("./openapi.yaml");
const generated = generateToolsWithTags(normalized, { prefix: "github" });

console.log(generated.tools[0]?.name);
```

The library entrypoint exports:

- `parseSpec`
- `generateTools`
- `generateToolsWithTags`
- `NormalizedSpec`

## Run

### stdio

```bash
npm run dev -- --spec ./openapi.yaml
```

### StreamableHTTP

```bash
npm run dev -- --spec ./openapi.yaml --transport streamable-http --port 3000
```

Endpoints:

- `http://localhost:3000/health`
- `http://localhost:3000/metrics`
- `http://localhost:3000/mcp`
- `http://localhost:3000/test/streamable`

### SSE (legacy)

```bash
npm run dev -- --spec ./openapi.yaml --transport sse --port 3000
```

Endpoints:

- `http://localhost:3000/health`
- `http://localhost:3000/metrics`
- `http://localhost:3000/sse`
- `http://localhost:3000/messages?sessionId=...`
- `http://localhost:3000/test/sse`

## CLI

```bash
mcp-openapi --spec  [options]
mcp-openapi init [dir]
mcp-openapi generate --spec  [--out-dir ./generated]
```

Options:

- `--server-url `
- `--cache-path `
- `--out-dir `
- `--strict`
- `--tool-name-template `
- `--print-tools`
- `--validate-spec`
- `--transport stdio|streamable-http|sse`
- `--port `
- `--watch-spec`
- `--timeout-ms `
- `--retries `
- `--retry-delay-ms `
- `--max-response-bytes `
- `--max-concurrency `
- `--allow-hosts host1,host2`
- `--allow-tools pattern1,pattern2`
- `--deny-tools pattern1,pattern2`
- `--allow-methods GET,POST`
- `--allow-path-prefixes /v1,/public`
- `--response-transform `
- `--sse-max-sessions `
- `--sse-session-ttl-ms `

Template placeholders for `--tool-name-template`:
- `{operationId}`
- `{method}`
- `{path}`
- `{tag}`

Response transform module example:

```js
export default function transform({ operation, response }) {
  return { ...response.body, transformedBy: operation.operationId };
}
```

## Auth env vars

- `MCP_OPENAPI_API_KEY`
- `MCP_OPENAPI_BEARER_TOKEN`
- `MCP_OPENAPI_BASIC_USERNAME`
- `MCP_OPENAPI_BASIC_PASSWORD`
- `MCP_OPENAPI_OAUTH2_ACCESS_TOKEN`
- `MCP_OPENAPI_OAUTH2_CLIENT_ID`
- `MCP_OPENAPI_OAUTH2_CLIENT_SECRET`
- `MCP_OPENAPI__TOKEN`
- `MCP_OPENAPI__CLIENT_ID`
- `MCP_OPENAPI__CLIENT_SECRET`

## Build and verify

```bash
npm run check
npm run build
npm test
npm run smoke
```

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [evalops](https://github.com/evalops)
- **Source:** [evalops/mcp-openapi](https://github.com/evalops/mcp-openapi)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-evalops-mcp-openapi
- Seller: https://agentstack.voostack.com/s/evalops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.