I connected a real weather API to Claude in 3 commands — and the community broke my tool in the best way

Furkan — Sat, 29 Aug 2026 00:06:54 +0000

How mcpify went from "it works on my examples" to surviving the live api.weather.gov spec — a story in OpenAPI archaeology.

The problem nobody warns you about

Every tutorial about connecting Claude (or Cursor, or any agent) to your own REST API ends the same way: "and now you write a custom MCP server."

If your API has 40 endpoints, that's 40 tool definitions. Parameter schemas. Validation. Error handling. Auth plumbing. And then your API changes next sprint — because real APIs change next sprint — and you do it again.

Here's the thing though: if your API has an OpenAPI document (Swagger), all the information an MCP server needs already exists. The paths, the parameter types, the required fields, the enums, the descriptions you wrote for humans. Writing a second, hand-maintained version of the same contract is busywork.

That's why I built mcpify: point it at any OpenAPI 3.x spec — file or URL — and it serves the whole API as an MCP server over stdio. No codegen. No wrapper repo. One command.

Bash

pipx install mcpify-openapi

mcpify list https://api.weather.gov/openapi.json --read-only
mcpify serve https://api.weather.gov/openapi.json --read-only
That second command wires 69 real tools into any MCP client — every National Weather Service endpoint, with typed parameters and enum'd values the model picks from a list instead of free-typing.

"It works on my examples" — famous last words

The first version was honestly naive. I tested it against the usual petstore-style specs and called it done. Then I did something better than writing more examples myself: I published it and let people throw real APIs at it.

They found the gaps fast:

$ref'd parameter schemas crashed it. The live weather.gov spec references #/components/schemas/... from its parameters — real-world OpenAPI does this everywhere. My resolver was being handed an empty spec. One line-level bug, every "serious" API dead on arrival.
GET-only isn't side-effect-free. A "read-only mode" that filters by HTTP method happily exposes GET /admin/reset-cache. Oops.
Circular $refs, multipart bodies, server URL variables, relative base URLs, 300KB responses — each one a small landmine that toy specs never step on.
The fix wasn't just patching these — it was building a hostile-spec corpus from published failure studies (there's a great arXiv paper on REST→MCP generation across 18 real APIs — its top-3 failure categories are all base-URL and auth-declaration problems). Every landmine is now a pinned regression test. The weather.gov spec loads in CI on every push. 82 tests total, mypy strict, ruff, CodeQL, Linux + Windows matrices.

That's the honest version of "production-grade": not a vibe, a checklist you re-run.

The parts I'm proudest of

The policy layer. After the GET-mutation feedback, --read-only got teeth:

Bash

mcpify serve api.json --read-only --deny '/admin' --allow '/search'
--deny hides paths no matter what (so that mutating GET is gone), --allow re-includes read-style POST endpoints (search-with-a-body is a read). Deny always wins — least surprise for whoever configures it.

Token-friendly scoping. Every tool description eats context tokens on every turn. A 200-endpoint API as 200 tools is how you get billed for a model re-reading a phone book. --tag payments, --include /v1/orders, --exclude /internal keep the surface to what the agent actually needs.

Secrets stay out of band. --auth-env API_TOKEN --auth-style bearer — the credential lives in the environment, gets injected at call time, and never appears in tool schemas, configs, or logs. The Authorization header param is stripped from advertised schemas so the model can't inject its own.

One tag = full release. Pushing v1.0.4 ships PyPI + the official MCP Registry (io.github.furkan708/mcpify) + a GitHub Release + a GHCR container image, via OIDC, no stored tokens.

Try it in 60 seconds

Bash

zero-install runner (uv):

uvx --from mcpify-openapi mcpify list ./openapi.json --read-only

or install:

pipx install mcpify-openapi

wire it into Claude Desktop (claude_desktop_config.json):

{
"mcpServers": {
"my-api": {
"command": "mcpify",
"args": ["serve", "./openapi.json", "--read-only"]
}
}
}
Or as a container: docker run -i ghcr.io/furkan708/mcpify:latest serve ./spec.json --read-only

What it deliberately doesn't do

Spec-less APIs — if there's no OpenAPI document, mcpify has nothing to project. (Garbage-in protection for both of us.)
Retries / rate limiting / circuit breakers — retrying a non-idempotent POST can duplicate side effects; those belong at your gateway, where they're observable. mcpify limits blast radius instead: read-only, deny policies, timeouts, truncated responses.
Webhooks & streaming — MCP-over-stdio is request/response today; remote transports are on the roadmap.
Being upfront about limits is part of the trust contract, same as the tests.

Repo: github.com/furkan708/mcpify · PyPI: mcpify-openapi · Docs: USAGE · Audit checklist

If you point it at a real API — your company's internal service, a public one, whatever breaks — I want to hear what blows up. Every crash report so far has made it better, and there's a good-first-issue list if you'd rather build than break.

DEV Community: Furkan

I connected a real weather API to Claude in 3 commands — and the community broke my tool in the best way

zero-install runner (uv):

or install:

wire it into Claude Desktop (claude_desktop_config.json):