# openapi-mcp

Point it at an OpenAPI 3.x document and get an MCP server that exposes the
API's endpoints as typed, validated tools for Claude or any MCP client.

```
pip install -e .

OPENAPI_SPEC=./openapi.json \
OPENAPI_AUTH_KIND=bearer OPENAPI_AUTH_VALUE=$TOKEN \
python -m openapi_mcp
```

Each operation in the spec becomes one tool. Parameter schemas come from the
spec itself, so the model sees real types and required fields instead of a
free-text prompt.

## Design choices

- **The model cannot call the API wrongly.** Every parameter carries its real
  JSON Schema, required fields are marked required, and unknown arguments are
  rejected rather than silently dropped. A tool that quietly ignores an
  argument is worse than one that errors, because the model believes it worked.
- **Errors are written for a model, not a human with a debugger.** An AI client
  cannot read a stack trace, but it can read "404, the user id does not exist".
  Failures come back as short factual sentences naming the status and the API's
  own message. Secrets never appear in them.
- **The whole test suite runs offline.** Transport is injected behind a
  Protocol, so tests run against a fake with no network and no cassettes.
  `PYTHONPATH=src python -m pytest tests/ -q`
- **Credentials are environment-only.** Command line arguments end up in shell
  history and in `ps` output; environment variables do not.

## Auth

`OPENAPI_AUTH_KIND` is one of `none`, `bearer`, `header`, or `query`, with
`OPENAPI_AUTH_VALUE` and (for header/query) `OPENAPI_AUTH_NAME`.

## Scope, stated plainly

This handles the OpenAPI subset that real-world REST APIs actually use: local
`$ref`, path, query and header parameters, JSON request bodies. It does not
resolve remote or URL `$ref`, and it does not attempt full JSON Schema
composition (`allOf` and `oneOf` pass through as-is). Unsupported input raises,
it never silently degrades. Cookie parameters are parsed but rejected at tool
build time, because sending cookies on a machine-driven call is a footgun.

## Claude Desktop config

```json
{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["-m", "openapi_mcp"],
      "env": {
        "OPENAPI_SPEC": "/path/to/openapi.json",
        "OPENAPI_AUTH_KIND": "bearer",
        "OPENAPI_AUTH_VALUE": "your-test-token"
      }
    }
  }
}
```

MIT licensed. Built and maintained by lumenpike.