Archstone — connect your business to every AI
A compiler for AI capabilities. Describe what your business can do once, in business terms. Archstone compiles it into tools an AI agent can discover and call — MCP today, other protocols as they arrive. Nobody hand-writes integration code.
Open source, Apache-2.0.
Find what you need
| I want to… | Go to |
|---|---|
| See it working in 60 seconds | Try it |
| Generate a manifest from my OpenAPI spec | Start from an API you already have |
| Install the CLI and know what each command does | Install · Commands |
| Understand the model (CDL → IR → tools) | How it works |
| Call capabilities from my own agent loop | Embed it |
| Know what Archstone guarantees | Guarantees |
| Learn the language | CDL specification · glossary |
| Walk through it end to end | Onboarding guide |
| Know what is free and what is sold | Open source and commercial |
| Contribute | Contributing |
Try it — 60 seconds, nothing to install
A capability compiled by Archstone is running live:
https://demo.archstone.dev/mcp
-
Claude app (web, desktop or mobile): Settings → Connectors → Add custom connector → paste the URL, then ask about a trip. Works on the Free plan.
-
Claude Code:
claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcpThe read-only tools need no key. The demo's booking tools do; its two public keys are listed in the showcase. To send one, add the server with the header after the name and URL (
--headertakes every word that follows it, so placed earlier it swallows them):claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp \ --header "Authorization: Bearer <key>"
The whole integration behind it is 12 lines of business YAML — no HTTP, no JSON Schema, no MCP SDK. Everything else was generated.
Want this in front of your own systems? hello@archstone.dev.
Start from an API you already have
archstone init openapi.yaml --out manifest --company acme --domain catalog
init drafts a manifest from an OpenAPI document, asks you what no spec can answer, and writes
nothing unless the result compiles.
Details: onboarding → archstone init.
The spec in the recording is examples/demo/stays-openapi.yaml.
Install
npm install -g @archstone/cli # or: npx @archstone/cli <command>
Node 22+. Your manifest lives in your own repository; the CLI is a stateless compiler that needs no checkout of this one (why).
Commands
| Command | What it does |
|---|---|
archstone init <openapi> | Draft a manifest from an OpenAPI document (or, with --source postgres --dsn-env <VAR>, from a Postgres catalog) |
archstone apply <dir> | Validate and compile to IR; --exposure lists what a model sees and what it never sees, and which capabilities are exposed, unlisted or not exposed (retired, unbound) |
archstone build <dir> | Write a portable IR artifact for embedding |
archstone serve <dir> | Serve MCP tools over stdio; --http --token <t> for HTTP |
archstone verify <dir> | Replay recorded fixtures against the live backend and report drift; --json for CI |
archstone doctor <dir> | Offline pre-production checklist |
archstone adopt <dir> | Declare a field the backend started returning (interactive) |
archstone audit <log> | Read back the execution audit trail |
apply also warns about what an irreversible capability still lacks — here, removing its
declared failures adds a warning, and restoring them clears it:
Each command is covered in the onboarding guide.
Working from a checkout of this repository instead? Use pnpm apply, pnpm serve, … — see
contributor onboarding.
How it works
capabilities.yaml → *.capability.yaml → bindings/*.binding.yaml
(what the company (each capability: (how a capability maps
offers — the index) business shape only) to a real backend)
└──────── archstone apply ────────┘ └── archstone serve ──┘
parse → validate → compile → IR emit MCP tools → agent
- CDL (Capability Definition Language) describes what you offer — business terms only.
- Bindings say how each capability reaches a backend (REST or SQL).
- The compiler lowers both to a target-agnostic IR; emitters turn the IR into tools.
Change the protocol and you regenerate instead of rewriting. Change the backend and the CDL does
not move. A worked example: examples/manifests/booking/.
Embed it in your own agent
No MCP server process needed — load a built IR with
@archstone/agent:
import { fromIR } from "@archstone/agent";
const archstone = fromIR(compiledIR);
const tools = archstone.tools("anthropic"); // or "openai-chat", "openai-responses", "gemini", "json-schema"
const result = await archstone.execute("tourism.search", { location: "Paris" });
A mountable Streamable-HTTP MCP handler is available at @archstone/agent/mcp. Full API:
packages/agent.
Guarantees
These are ratified decisions, not implementation details — each links to its reasoning.
| Guarantee | Decision |
|---|---|
| A provider field your manifest does not declare never reaches a model | ADR-0008 |
| A field a model invents never reaches your system | ADR-0011 |
build and serve never need a network call, an account or a key | ADR-0005 |
| No feature that is free today becomes paid | ADR-0005 |
| Ranking in any selection Archstone performs is not for sale | ADR-0006 |
effect (read / write / irreversible) is confirmed by a person, never inferred | Onboarding |
All decision records: docs/adr/.
Who is running it
ArtVinci, a custom-framing business, answers customer questions through a capability compiled by Archstone — real catalog, prices computed live by their own backend. Case study.
Why a compiler, and not an MCP server
The first MCP server is an afternoon's work. The fifth — ChatGPT, Gemini and whatever ships next, each shaped slightly differently, all on top of an API that keeps changing — is the real cost. Archstone is a compiler that, in its first release, generates an MCP server, so that maintenance does not multiply with every new protocol.
Open source and commercial
Everything needed to turn a manifest into something an agent can call — language, compiler, IR, emitters, embedded SDK and CLI — is Apache-2.0 and stays that way. What we will sell is operating it for you: hosted audit retention, managed rate limits, drift monitoring and multi-tenant hosting. See ADR-0005.
Documentation
| Topic | Where |
|---|---|
| Onboarding (providers, embedders, contributors) | docs/ONBOARDING.md |
| CDL specification (normative, 1.0, frozen) | docs/cdl-specification.md |
| Why CDL looks the way it does | RFC-0002 |
| Machine schema | cdl.schema.json |
| Glossary | docs/glossary.md |
| Identity and principals | docs/IDENTITY.md |
| Architecture decisions | docs/adr/ |
| End-to-end demo with Claude | examples/demo/README.md |
| Supported versions | SUPPORT.md |
Repository layout
packages/
schema/ load and shape-validate manifests (cdl.schema.json)
compiler/ semantic validation, lowering to IR
emitter-support/ shared substrate for every emitter
runtime/ registry, MCP emitter and transport, verify
agent/ embedded SDK
init/ OpenAPI → manifest drafting
cli/ the archstone command
providers/
rest/ sql/ backend adapters
examples/ manifests and the Claude demo
docs/ spec, ADRs, RFCs, onboarding
How this project uses generative AI
Archstone is written with substantial AI assistance — Anthropic's Claude, through Claude Code —
for implementation, tests and documentation. The decisions are not generated: every
structural choice is an ADR, argued and ratified by an accountable person before the code, and
a patch nobody can explain does not merge. Commits with generated code name the model in their
co-authorship trailer. What we ask of contributors:
CONTRIBUTING.md.
Contributing
CONTRIBUTING.md and the
contributor onboarding. Node 22+, pnpm 11+;
pnpm typecheck && pnpm test green before you open a PR.
License
Copyright 2026 NousVigil LLC. Licensed under Apache-2.0; see also NOTICE.