The first Agentify article had the right source and the wrong article. It treated the project as a generic shortcut for AI integration. That language hides the engineering problem Agentify actually touches: agent teams now keep the same API knowledge in too many places.

A public API may need an MCP server, a CLAUDE.md, an AGENTS.md, Cursor rules, a skills.json, a CLI wrapper, and a short LLM-readable summary. If those files are written by hand, they drift. If they are generated blindly, they can expose too many tools or describe unsafe operations too casually. Agentify is useful because it starts from one OpenAPI contract, but it only belongs in a serious workflow when the generated surface is treated as a draft to review.

The useful frame is contract compilation

Agentify should be read as an interface compiler, not a magic API assistant. The README's core promise is concrete: OpenAPI in, agent interfaces out. The supported outputs cover the surfaces where agents work today: MCP server code, CLAUDE.md, AGENTS.md, .cursorrules, skills.json, llms.txt, GEMINI.md, A2A discovery, and a standalone CLI.

That matters for Codex and Claude Code because an API contract is often the closest thing to repo truth. If a payment service, internal admin API, or deployment platform already maintains an OpenAPI spec, Agentify can turn that contract into a first MCP server and matching agent docs. The gain is not that every generated file is final. The gain is that the first draft uses the same source of truth instead of nine separate summaries.

Run parse before transform

The safer adoption path starts with parse, not with a full output directory:

npx agentify-cli parse ./openapi.yaml --summary

The parser builds an intermediate representation with product metadata, domains, capabilities, auth config, generation strategy, input and output schemas, HTTP metadata, side-effect flags, and idempotency. That summary tells the reviewer what Agentify thinks the API is before any MCP tool is exposed.

Use the parse output to answer three questions. Are the domains sane, or did the spec tags produce a messy grouping? Did auth detection pick the right API key, bearer, OAuth, basic, or custom shape? Are destructive operations marked as side-effecting? If the answer is weak, fix the spec or generate from a curated spec subset before moving forward.

Generate a small surface first

The CLI can emit many formats, but the first pass should be narrow:

npx agentify-cli transform ./openapi.yaml -f mcp agents.md claude.md -o ./agent-api
cd ./agent-api
npm install
cp .env.example .env
npm start

The default CLI format list includes mcp, claude.md, agents.md, cursorrules, llms.txt, gemini.md, skills, and a2a; the registry also has cli. That breadth is convenient for demos, but it is too much as a first team rollout. Start with the MCP server and the two instruction files your team actually reads. Add .cursorrules, skills, A2A, or CLI output after the generated MCP shape has survived review.

Make the first PR intentionally small

The first PR should not say generated everything. It should include one generated MCP server, two edited instruction files, and a short note explaining which endpoints were removed. Keep the diff readable enough that a reviewer can inspect every tool.

A concrete first PR checklist looks like this:

node --version             # Agentify requires Node 18 or newer
npx agentify-cli parse ./openapi.yaml --summary > .agentify-ir-summary.txt
npx agentify-cli transform ./openapi.yaml -f mcp agents.md claude.md -o ./agent-api
cd ./agent-api
npm install
npm run build
rg -n "server.tool\(" src/tools.ts

Attach .agentify-ir-summary.txt to the review or commit it if the team wants an audit trail. The reviewer should compare the IR domains with the generated tool names, then ask which of those tools a coding agent should be allowed to call during normal tasks. If the answer is not obvious, remove the tool or regenerate from a narrower OpenAPI slice.

What the MCP emitter really writes

The MCP emitter is the most important code path to inspect. It writes src/index.ts, src/tools.ts, src/handlers.ts, package.json, tsconfig.json, Dockerfile, .env.example, and README.md. The generated server uses the MCP SDK over stdio. Tool definitions use Zod shapes from the parsed input schema. Handlers replace path parameters, split query and body parameters, attach auth headers from environment variables, call fetch, and return MCP text content.

That is enough to stand up a real local tool server, but it is not the same as a production tool design. OpenAPI operation names are not always good tool names. Some specs model internal admin endpoints next to safe read endpoints. Some POST endpoints are idempotent in practice; some GET endpoints are expensive. A reviewer should read src/tools.ts and src/handlers.ts before adding the server to a shared MCP config.

Review the generated server like a dependency

After generation, review the output before it reaches Claude Code, Codex, Cursor, or a teammate's desktop. A small first pass is mechanical:

cd ./agent-api
npm run build
rg -n "delete|remove|invite|token|secret|billing|admin|deploy|write|create|update" src/tools.ts src/handlers.ts
rg -n "process.env|Authorization|API_BASE_URL|fetch\(" src/handlers.ts .env.example

The first command proves the generated TypeScript compiles. The second finds operations that deserve a human decision before they become tools. The third checks where credentials, base URLs, and network calls are wired. If the generated surface includes destructive actions, remove those registrations from src/tools.ts or regenerate from a smaller spec. If auth is wrong, fix the OpenAPI security scheme before patching generated code by hand. If the tool list is too large to read in one review, the spec slice is too broad.

Use parse output for setup failures

Most Agentify failures should send the team back to the spec or IR, not straight into generated code. If a remote spec fails, download it and run from a local file so the review has a stable artifact. If strict validation fails but lenient parsing succeeds, read the warning before publishing generated tools. Lenient parsing is useful for messy real specs, but it also means the generator had to normalize something.

If auth lands in the wrong header, fix the OpenAPI securitySchemes entry and regenerate. If path or query parameters look wrong, inspect the IR capability for that operation before editing src/handlers.ts. If there are too many tools, do not hide them with docs. Trim the spec input. This keeps Agentify as a repeatable compiler step instead of a one-time code dump that nobody can regenerate.

The docs emitters are a starting point

AGENTS.md and CLAUDE.md output is useful because it keeps the generated docs close to the same IR as the MCP tools. The AGENTS emitter writes identity, capabilities by domain, authentication, protocol notes, constraints, side-effect counts, and generation strategy. The Claude emitter writes overview, auth setup, domain tables, endpoint reference, and usage notes.

The project's own self skill gives the better editorial rule: generate deterministic code, but let an agent or human author the final natural-language docs from parse output. A template can list endpoints. A good AGENTS.md explains which workflows should be used, which operations should be avoided, what order calls happen in, which scopes are required, where rate limits matter, and which actions have side effects. Agentify supplies the raw map; the article-worthy work is turning that map into operating guidance.

Security scan passed is not a permission slip

Agentify does include two safety layers. The parser sanitizes spec fields, removing code execution patterns, Handlebars expressions, template interpolation, script tags, process access, and common prompt-injection strings. The generated-output scanner checks produced files before writing them. Critical eval and new Function findings block output; high and medium findings become warnings.

That is useful defensive plumbing, but the boundary needs to be explicit. A scan pass only says the generator did not emit code matching the scanner's critical patterns. It does not say a generated MCP tool is safe for an agent to call. Review the operation list for deletion, billing, invitation, credential, deployment, and admin actions. Add auth scopes deliberately. Pin packages. Keep generated server paths narrow. Treat scanner warnings as review items, not console noise.

Large APIs need pruning before generation

The README lists project-provided scale tests against APIs from small examples to GitHub-sized specs. That is valuable as a stress signal, but it should change how a team uses the tool. A 20-endpoint Petstore server is reviewable. A 452-endpoint Stripe surface or 1,093-endpoint GitHub surface is not something to drop into an agent as one flat tool belt.

For large APIs, create a curated OpenAPI file or filter the spec before generation. Pick one workflow, such as issue triage, deployment status, customer lookup, or invoice read-only support. Generate only that slice. Keep the rest behind normal developer review. The cost of exposing hundreds of operations is not just token use; it is decision noise. Agents choose worse when every rare endpoint looks as available as the safe read path.

Where it fits in a Codex workflow

Agentify fits best at the boundary between API maintenance and agent setup. Put the command next to the spec, for example in a make target or package script, so the generated MCP server and instruction files can be rebuilt when the OpenAPI contract changes. Commit the generated output only if the repo treats it as source with review, tests, and ownership.

A practical Codex task would look like this:

npx agentify-cli parse ./openapi.yaml --summary > .agentify-ir-summary.txt
npx agentify-cli transform ./openapi.yaml -f mcp agents.md claude.md -o ./agent-api
cd ./agent-api
npm install
npm run build
npm start

Then inspect the generated tool names, remove tools the agent should not call, edit AGENTS.md into workflow rules, add the server to a local MCP config only after one safe read call works, and record the regeneration command in the parent repo. That is a real workflow. The old article's generic AI-integration framing missed it.

Use it when the contract is owned

Agentify is a bad fit when the OpenAPI spec is stale, incomplete, or copied from an external service the team does not control. It is also a bad fit when the desired agent behavior needs hand-built guardrails, approval steps, pagination policy, caching, or domain-specific retries. In those cases, write a small MCP server by hand or generate once and then harden manually.

Use Agentify when the API contract is maintained, the desired tool surface is bounded, and the team wants one repeatable path to MCP plus agent docs. The best result is not a folder full of generated files. The best result is a short, reviewed interface layer that can be regenerated from the same contract and still reads like it was designed for agents rather than copied from HTTP docs.

Save Agentify as a contract-to-interface compiler article. It is valuable when teams parse first, generate a small MCP and documentation surface, prune risky endpoints, and review generated handlers; it is weak when framed as one-command API adoption.

Practical takeaway

Run agentify parse ./openapi.yaml --summary, generate only mcp agents.md claude.md for the first pass, review src/tools.ts and src/handlers.ts, remove destructive or noisy operations, edit the instruction files into workflow guidance, test one safe read call, then document the exact regeneration command in the repo.