Keystone

Keystone

Understand your system before you change it.

Keystone keeps a C4 model of your software: systems, services, components with their public API, databases down to tables and columns, scenarios and architecture decisions. Your AI coding assistant builds the model from the code in your environment, keeps it in step with the code and reads it back over MCP as context for its next task. Every change arrives as a branch that your team reviews.

• Website: https://keystone-core.pro
• Live demo, no sign-up: https://keystone-core.pro/demo
• Guide: https://keystone-core.pro/docs
• MCP server: https://keystone-core.pro/mcp (Streamable HTTP, bearer token)

This repository holds no source code: it is the public home of Keystone for its MCP server, docs links and feedback.

What it does

• Builds the architecture from code. Your AI reads the repository where it already works and proposes the model: context, containers, components, ER diagrams from migrations. Keystone never receives your source code.
• Gives the agent the part it needs. The agent asks for one module, what depends on an element, the path between two elements or only what changed since last time, instead of the whole model.
• Keeps the model current. After code changes the AI checks the diagram against the code and sends a proposal, by hand or from CI: the AI assistant generates the job for GitHub Actions or GitLab CI.
• You stay the reviewer. Every AI proposal arrives as a branch: open it, correct it, merge it or reject it. Merges are three-way, field by field.
• More than boxes. Scenarios, architecture decisions (ADR) bound to elements, impact analysis, antipattern review with remediation plans, comments, live co-editing, roles and access, system design interview practice.
• No lock-in. Export to PNG, SVG, Markdown with Mermaid, Structurizr DSL and Obsidian notes; import a Structurizr workspace (JSON or DSL).

On a question about one module, the module slice took 68–77% fewer input tokens than sending the whole model, with the same facts in the answer. This compares a slice with the whole model, not a whole coding task (method and limits).

Claude Code plugin

Install Keystone as a plugin; Claude Code asks for your token once and keeps it in secure storage:

/plugin install keystone-architecture --marketplace runafterasun/keystone-core

Connect your AI

1. Sign in at https://keystone-core.pro and open a project → AI assistant → Connection → Create token.
2. Add the MCP server in the folder with the code of that project, or install the plugin above.

Claude Code

claude mcp add --scope local --transport http keystone https://keystone-core.pro/mcp --header "Authorization: Bearer ks_…"

Cursor (.cursor/mcp.json)

{ "mcpServers": { "keystone": { "url": "https://keystone-core.pro/mcp", "headers": { "Authorization": "Bearer ks_…" } } } }

VS Code with GitHub Copilot (.vscode/mcp.json)

{ "servers": { "keystone": { "type": "http", "url": "https://keystone-core.pro/mcp", "headers": { "Authorization": "Bearer ks_…" } } } }

Gemini CLI (.gemini/settings.json)

{ "mcpServers": { "keystone": { "httpUrl": "https://keystone-core.pro/mcp", "headers": { "Authorization": "Bearer ks_…" } } } }

Windsurf (~/.codeium/windsurf/mcp_config.json)

{ "mcpServers": { "keystone": { "serverUrl": "https://keystone-core.pro/mcp", "headers": { "Authorization": "Bearer ks_…" } } } }

Clients with local (stdio) servers only, through the mcp-remote bridge (needs Node.js):

{ "mcpServers": { "keystone": { "command": "npx", "args": ["-y", "mcp-remote", "https://keystone-core.pro/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer ks_…" } } } }

A token follows the current role of its owner in the project: a viewer's token only reads. More in the guide.

Prompts

Ready commands the server offers to your client, for example in Claude Code /mcp__keystone__build_architecture <project link>:

Tools

Reading tools return the part of the model a task needs:

Changes go through propose_changes only: a proposal becomes a branch that a person reviews and merges. Checks against the code and antipattern findings are reported with report_validation and report_antipatterns.

Plans and hosting

• keystone-core.pro has a free plan with limits.
• Self-hosted inside your own network for companies: contact us.

Feedback

Questions, ideas and bug reports are welcome as issues.