Overview

Partifact is a working demonstration that an API can be designed for AI agents as first-class consumers. It is a faithful mock of a real automotive parts-procurement Integrations API — the “Rails” platform, 2026-01 contract — wrapped in the developer surfaces an API needs in 2026: a typed SDK, machine-readable docs, and two MCP servers.

The claim it makes is concrete:

AI agents are a new class of API consumer. They install your API, read your docs, reason about your contract, and call your endpoints — but they are neither a human reading a portal nor a hand-written SDK. Design for them as first-class consumers and the same API serves two audiences at once.

So Partifact serves both. A human reads these pages. An agent connects an MCP and either operates the procurement lifecycle or builds an integration against the API — and that agent’s unaided success is the actual test.

This is a demonstration artifact

Partifact is an independent sandbox that faithfully mirrors the shape of a real parts-procurement API contract — it is not an official vendor product or service. Where it simplifies or extends the contract, it says so (see the honesty boundary below).

Two consumer classes — the system is built for both

The runtime agent

An agent that operates the business workflow — opens a repair job, gets a parts basket, places and confirms an order, reconciles the invoice. It connects the Rails MCP and calls intent-level tools. It never writes HTTP by hand.

The integration developer

An agent (or a human pairing with one) that builds a client against the API — a webhook receiver, an SDK, a sync job. It reads the API docs and /openapi.json, or queries the Docs MCP, and writes code.

What ships

| Piece | What it is | Where | |---|---|---| | Mock API | A faithful mock of the 2026-01 contract — RPC-over-POST, OAuth install, signed webhooks, typed OpenAPI. | partifact-mock-rails.thanhvuttv.workers.dev | | Typed SDK | A hand-written, contract-derived TypeScript client (repairer.jobs.insert(...)), mirroring generated-SDK ergonomics. | in the repo | | Rails MCP | The headline: 13 intent-level tools + 8 resources that drive the lifecycle, built on the SDK. | Connect → | | Docs MCP | The docs exposed as 3 read-only tools. Public. | Connect → | | Docs portal | One markdown source rendered for humans and agents (/llms.txt, raw .md, /openapi.json). | API reference ↗ |

All three servers are live on Cloudflare Workers — you can connect and test without cloning or building anything.

Get started in three steps

1. Pick a server. Connect the Rails MCP to drive the procurement workflow as an agent, or the Docs MCP to let an agent read the docs as tools. You can connect both.
2. Connect Claude. A remote URL in claude.ai (easiest — nothing to install), a config block in Claude Desktop, or one command in Claude Code. First, grab credentials & tokens.
3. Hand it the work. Ask Claude to run the seeded repair job end to end, or to build an integration against the API. Everything it needs is in the docs and the typed spec.

The honesty boundary

Calibrated honesty is the point, not a disclaimer. Three lines are held everywhere, including inside the tools and docs themselves:

Faithful vs. proposed extension

The public 2026-01 lifecycle terminates at order_confirmed. Two steps that complete the buyer’s loop — place_procurement (repairer.procurements.insert) and reconcile_invoice (repairer.procurements.invoices.list) — are a clearly-labelled proposed extension, not part of the public contract. They announce themselves at runtime (is_extension: true / x_extension: true) and carry a verbatim banner wherever they appear. Treat them as a proposal.

• The basket carries no currency. Currency is a procurement-level concept; it first appears later in the lifecycle as currency_code on the procurement. If you read a currency off a basket offer, you are inventing it.
• Single-process simplifications are documented. In a single-agent run the supplier-confirm step and webhook delivery are collapsed; the envelopes and state machine stay byte-faithful. The full list lives in the repo’s Fidelity & simplifications notes.

This is faithful to the API’s shape — endpoint names, headers, auth flow, error model, webhook signing, date-versioning — and deliberately not a reproduction of a production stack (Rust / Kafka / ScyllaDB), which would be neither necessary nor honest to fake.

Where to go next

Set up Claude Start with the remote connector — nothing to install.

Credentials & tokens How to get the API key and the MCP access token.

The API at a glance RPC-over-POST, the lifecycle, webhooks, the typed spec.

Let the AI do the coding Point Claude at the docs and have it build the integration.