Archstone
Compile your own business capabilities from declarative YAML and serve them as MCP tools.
Install Archstone
Pick your client, then add it in one click or paste the config.
No confirmed install command yet
We only publish a config when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for archstone, and we’d rather show nothing than a guess you’d paste into your client.
Open setup steps on GitHubOverview
From the project README
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 |
| 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
Security & health
What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.
ActiveLast checked 4d ago
Recent health check succeeded.
8/8 checks healthy over the last 50d
Supply-chain signal
No high-severity advisories surfaced by our automated scan.
Critical 0High 0Medium 0Low 0
Scanned 11d ago via OSV.dev
Adoption & maintenance
Factual signals from GitHub, npm, and our automated checks — not a rating.
GitHub stars6Stargazers on the source repository.
npm downloads2.9kPackage downloads in the last 30 days.
Last commit4d agoMost recent push to the default branch.
Reviews
No reviews yet — be the first to share how it worked for you.
Frequently Asked Questions about Archstone
archstone is an MCP server that compiles declarative YAML business capability definitions into discoverable tools for AI agents. It uses a compiler pipeline from CDL to an intermediate representation and serves the resulting capabilities through MCP. You can start from an OpenAPI document, keep manifests in your repository, and run the open-source Apache-2.0 CLI.
Install archstone with Node 22 or newer using `npm install -g @archstone/cli`, or run commands without installation through `npx @archstone/cli <command>`. Your manifest remains in your own repository, and the CLI operates as a stateless compiler.
Yes, `archstone init openapi.yaml --out manifest --company acme --domain catalog` drafts a manifest from an OpenAPI document. The command asks for information an API specification cannot provide and writes the result only if it compiles successfully.
Run `archstone serve <dir>` to serve compiled capabilities over MCP using stdio. For HTTP, use `archstone serve <dir> --http --token <t>`. Use `archstone apply <dir>` to validate and compile a manifest, or `archstone build <dir>` to create a portable IR artifact for embedding.
Related MCP servers
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/archstone)HTML Embed
<a href="https://allmcps.com/mcp/archstone"><img src="https://allmcps.com/api/badge/archstone?style=directory" alt="Archstone on AllMCPs" /></a>