archstone

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/mcp
  

  The 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 (--header takes 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? [email protected].

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 SQL connector guide walks through a Postgres one.
• 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/
A Postgres database as a backend (sql connector)	docs/guides/sql-connector.md
End-to-end demo with Claude	examples/demo/README.md
Supported versions	SUPPORT.md
Reporting a vulnerability	SECURITY.md — never a public issue
Changes	CHANGELOG.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.