Version-pinned API tools for coding agents

Why docs context is not enough

Docs retrieval helps agents answer questions, but API work often needs more than a relevant paragraph. The agent needs to know which operation exists, which parameters are valid, which credentials are required, and whether the call is destructive. A pasted page or a retrieved section can describe those details, but it does not turn them into a callable, version-aware tool.

That is the new Docmancer wedge: local, version-pinned API MCP packs for coding agents. The docs index still matters, especially when a package cannot compile into typed tools, but the main workflow is now about giving agents a tool surface they can safely search and call.

The baseline flow

The first-run path should feel like installing a docs pack, not configuring a hosted integration platform:

pipx install docmancer --python 3.13
docmancer setup
docmancer install-pack open-meteo@v1
docmancer mcp doctor

setup connects local agents. install-pack installs the pack artifacts and updates the local manifest. mcp doctor verifies artifact hashes, agent configuration, and credentials. The Open-Meteo demo is keyless, so the doctor passes immediately on a fresh machine.

For supported sources, Docmancer can fall back to the public OpenAPI spec when precompiled artifacts are unavailable. Users should not need to copy pipeline artifacts or configure a registry URL for the happy path.

Then the agent can answer a concrete prompt without any credential setup:

Get the current weather in New York Central Park.

It searches the installed tools, selects open_meteo__v1__forecast, and calls:

GET /v1/forecast?latitude=40.7812&longitude=-73.9665&current_weather=true

That is the baseline demo: a keyless pack, a versioned tool name, and a real API response from the local MCP runtime.

Local execution is the product boundary

Docmancer is not trying to become a hosted API execution service. The agent launches docmancer mcp serve locally, and the runtime reads installed pack files from the user's Docmancer home. Credentials are resolved from the local environment when a tool runs.

That boundary keeps the trust model simple. Pack files can describe that a keyed API requires a <PACKAGE>_API_KEY, but they do not contain the key. The local dispatcher checks for the credential before execution and returns an actionable refusal when it is missing. Keyless packs (like the Open-Meteo demo) skip credential resolution entirely.

Tool Search keeps startup small

Many APIs have hundreds of endpoints. Giving every operation to the agent at startup is noisy and expensive. Docmancer uses a Tool Search pattern instead. The local MCP server exposes two meta-tools:

• docmancer_search_tools
• docmancer_call_tool

The agent searches for an operation, receives a versioned tool name, then calls that operation. This keeps the initial MCP surface small while still making the full pack available when needed.

Safety needs to be visible

Generated tools are only useful if they fail closed. Docmancer blocks destructive operations unless the user explicitly opts in:

docmancer install-pack <pkg>@<version> --allow-destructive

The dispatcher also validates arguments before execution and applies idempotency keys for non-idempotent calls when the API contract declares an idempotency header. These controls should be visible in the CLI, docs, and website because they are part of the product promise, not implementation trivia.

The Open-Meteo demo has no destructive endpoints, but the gates still matter for keyed packs and broader API surfaces.

Where docs retrieval fits now

Some sources will not compile into typed tools. Some agent tasks need explanation rather than execution. In those cases, the original Docmancer docs workflow remains useful:

docmancer add https://docs.example.com
docmancer query "How do I authenticate?"

The product hierarchy is clear: typed, version-pinned tools when structured source material supports them, grounded docs context when it does not.