How Anvil works

Anvil compiles API contracts into agent-facing tools.

The API contract gives Anvil transport facts: paths, methods, fields, schemas, and auth schemes. It usually does not tell Anvil whether a call moves money, can be retried, needs confirmation, or is approved for agent use.

You supply those missing facts in a reviewed manifest.

API contract + reviewed manifest -> AIR -> CLI / MCP / SDKs / skill / hooks

AIR is the Anvil Intermediate Representation. Every generated surface comes from it.

Follow one operation

Take POST /refunds.

The API contract can prove the request and response shape. It cannot prove that retrying the call will not create a second refund.

Put that policy in the manifest:

operations:
  createRefund:
    side_effect: mutation
    risk: financial
    reversible: false
    idempotency:
      strategy: required_request_key
      key_location: header
      header: Idempotency-Key
    confirmation:
      required: true
      reason: This operation moves money and cannot be reversed.

Anvil then:

captures the exact source bytes;
combines source facts and reviewed facts in AIR;
validates effect, retry, confirmation, auth, and approval together;
generates each surface from AIR; and
checks the same policy again at runtime before network access.

The result is simple: the refund has the same name, schema, confirmation rule, and idempotency rule everywhere.

One operation, several ways to call it

fig 05 · pick any entry point — they all land on the same contract

Surface	Used by	What it does
CLI	Developer or CI	Inspects and invokes approved operations
MCP server	Agent runtime	Exposes approved operations as MCP tools
Client SDKs	Application code	Calls the same operations from TypeScript, Python, Go, or Java
Skill	Agent	Describes setup, capabilities, constraints, errors, and examples
Harness hooks	Coding harness	Refuses or escalates earlier in the call path

These are generated views of one contract. They are not separate integrations.

Do not edit generated files. Change the source contract or manifest and compile again.

Approval controls exposure

Classification says what an operation does. Approval says whether it may be called.

fig 07 · nothing reaches an agent until a human moves it to approved

State	Meaning
`generated`	The operation exists in AIR
`review_required`	A missing fact or decision blocks exposure
`approved`	The operation may enter callable surfaces
`blocked`	A known condition prevents approval
`deprecated`	The operation remains recorded but is removed from normal use

Only approved operations are callable.

Names are not evidence. getTransferStatus may still mutate state. HTTP methods are not enough either. Review the operation before approving it.

Runtime rules

If	Then
Effect is uncertain	Keep the operation `review_required`
Mutation idempotency is unproven	Disable automatic retry
Required confirmation is absent	Return `confirmation_required`
Durable deduplication is required but unavailable	Fail the write closed
Host is outside the reviewed allowlist	Return `policy_denied`
A hook is unavailable	Enforce the rule in the runtime

Hooks improve feedback. They are not the trust boundary. The runtime owns the final validation, auth, idempotency, retry, host, and execution checks.

What a bundle contains

anvil compile writes three kinds of artifact:

Contract: AIR, source identity, evidence, catalogs, and policy.
Generated surfaces: CLI, MCP, SDKs, skill, hooks, mocks, evaluations, target kits, and deployment inputs.
Assurance: certification, self-test, conformance, simulation, and publication records tied to the bundle hash.

Run anvil status <bundle> when you return to a bundle. It reports the first action still required.

Evidence is tied to bytes

Command	Question
`anvil certify`	Do generated artifacts agree with AIR?
`anvil selftest`	Does the generated MCP surface work over local transport?
`anvil conformance`	Do the generated CLI, MCP server, and skill agree?
`anvil simulate`	Do controls hold across the generated safety matrix?

Each record names the bundle hash it tested. Change the bundle and the record is stale.

anvil publish requires current evidence and creates an operator plan. It does not deploy.

Pick the right input path

API contracts use compile or agentify.

Gateway exports use the estate workflow. Gateway identity, policy, coordinates, and provenance need to survive import.

Application-server, .NET, and broker configuration use the legacy workflow. That workflow records offline evidence and reviewed bindings. It does not create a runnable deployment-local bridge in the current release.

Existing MCP servers use anvil adopt. A tool without a clear read-only signal stays a mutation until someone reviews it.

Anvil parses OpenAPI, Swagger, GraphQL SDL, proto3, WSDL, Google Discovery, OData metadata, and Postman collections. Parser support does not imply native wire support. See source format support.

What Anvil does not do

Anvil does not:

invent business meaning;
approve uncertain mutations;
store production credentials;
replace upstream authorization;
fetch remote references during local source capture;
turn inventory into execution authority; or
deploy when publish runs.

See the product boundary for the full ownership model.