API MCP Packs

What API MCP packs are

API MCP packs are local tool bundles for a specific API version. A pack contains the API contract, curated and full tool lists, auth metadata, provenance, safety rules, and hashes for installed artifacts.

Docmancer uses these packs to expose version-pinned tools to agents through a local MCP runtime. The agent does not receive hundreds of tools at startup. It receives two meta-tools:

docmancer_search_tools
docmancer_call_tool

The agent searches for the right operation, then calls the selected versioned tool.

Quickstart

Install Docmancer:

pipx install docmancer --python 3.13

Connect your agents:

docmancer setup

Install the Open-Meteo weather pack (no API key required):

docmancer install-pack open-meteo@v1

The installer resolves artifacts in this order:

Local cache.
The hosted Docmancer artifact API.
Built-in known-source fallback. The Open-Meteo pack can compile locally from the public OpenAPI spec when precompiled artifacts are unavailable.

Users do not need to configure a registry URL or copy pipeline artifacts.

Credentials

Docmancer does not write secrets into pack files. For packs that do require credentials, set the relevant <PACKAGE>_API_KEY env var in your shell before running docmancer mcp doctor. The Open-Meteo demo skips this step entirely.

docmancer mcp doctor

mcp doctor checks installed artifacts, agent registration, and required credentials:

[ok] package open-meteo@v1: artifact hashes match
[ok] package open-meteo@v1: no credentials required
All checks passed

Using packs from agents

After docmancer setup, supported agents launch Docmancer through their MCP configuration. Once a pack is installed, return to the agent and ask for the API task:

Get the current weather in New York Central Park.

The agent searches installed tools, selects open_meteo__v1__forecast, and dispatches this call through your local docmancer mcp serve process:

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

Open-Meteo answers with the current weather for New York Central Park.

Installed packs live under your Docmancer home:

~/.docmancer/
  mcp/
    manifest.json
  servers/
    open-meteo@v1/
      contract.json
      tools.curated.json
      tools.full.json
      auth.schema.json
      provenance.json

The hosted registry is not required at serve time. The MCP runtime reads the local manifest and local artifacts.

Safety gates

Each operation carries safety metadata. The dispatcher applies these controls before any executor runs:

Auth checks verify required credentials are available (skipped for keyless packs like open-meteo).
Destructive operations are blocked unless the pack was installed with --allow-destructive.
Non-idempotent operations receive an idempotency key when the contract declares an idempotency header.
Input arguments are validated against the operation schema.

To allow destructive operations for a pack, reinstall it with explicit opt-in:

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

Common commands

docmancer mcp list
docmancer mcp doctor
docmancer mcp disable open-meteo --version v1
docmancer mcp enable open-meteo --version v1
docmancer uninstall open-meteo@v1

Use --expanded when you want the full tool surface instead of the curated subset:

docmancer install-pack open-meteo@v1 --expanded

Pairing with docs retrieval

Typed tools are the best path when an API has structured source material. For grounded explanatory context, pair packs with hybrid docs retrieval:

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

Use API MCP packs when your agent needs callable, version-pinned operations. Use docs retrieval when your agent needs explanatory context, or when a package does not have a typed pack yet. Both share the same Docmancer home and the same agent skills installed by docmancer setup.

For installing packs from an arbitrary OpenAPI spec URL, use --from-url:

docmancer install-pack my-api@v1 --from-url https://example.com/openapi.yaml