What is adrkit MCP?
adrkit treats architecture decision records (ADRs, short documents that record a design choice and why) as typed data: Markdown files in git with YAML frontmatter, a status such as accepted, rejected or superseded, and an affects field that ties each decision to paths or packages. Its @adrkit/mcp package is a local stdio server that lets an agent search that corpus, fetch a record, list the decisions governing a set of files, and list what has been superseded.
The project is by Mark Beacom (GitHub user mbeacom), Apache-2.0-licensed and written in TypeScript for Node 22 or later. It is listed in the official MCP registry as dev.adrkit/mcp. Version 0.20.0 was released on 11 October 2026; the repository had 24 stars and a last push on 7 November. The same monorepo ships a CLI, a GitHub Action that comments governing decisions on pull requests, and a Claude Code and Copilot plugin.
How to install adrkit MCP
npx -y @adrkit/mcp --cwd /path/to/repo --dir docs/adrIs adrkit MCP worth it?
The point of adrkit's server is the graveyard. list_superseded and the history section of get_decision_context return rejected and superseded decisions alongside accepted ones, so an agent planning a change to src/db/ sees that MySQL was tried and replaced before it proposes MySQL again. Generic memory servers store what an agent chose to save; this one reads records people reviewed and merged.
The surface is four tools, all annotated read-only and closed-world: search_decisions (literal substring search over id, title, tags and body), get_decision, get_decision_context for up to 256 repository-relative files, and list_superseded. get_decision_context compares paths against each record's affects patterns and never opens the files. Results page at 20 by default and 100 at most, and records over 64 KiB are excluded with a finding rather than truncated. That keeps the context cost small and predictable.
The catch is that the value depends entirely on a corpus that most teams do not have. Records need adrkit's frontmatter and, for file matching, a well-kept affects field; adr migrate --from madr adds that to an existing MADR corpus, but someone still has to write the patterns. The project is pre-1.0 and its own README asks users to pin a version. Search is literal substring matching, with no ranking or embeddings by design, so the agent has to guess the words a record uses. The agent plugin deliberately ships no MCP config because Copilot CLI starts plugin servers outside the repository, so each project wires the server itself.
On security this is about as narrow as an MCP server gets. It reads Markdown under one directory inside one git worktree, rejects symlink escapes, makes no model or network calls, opens no port and writes nothing. The prompt-injection exposure is the record bodies themselves, which anyone who can merge to the repository can edit. The separate REST server in the container image is a different matter: it authenticates no one, and the README warns that anyone who can reach its port can read every corpus it serves.
Where it earns its place
A platform team of eight with 60 ADRs in docs/adr
Stop the coding agent re-proposing the queue system the team rejected last year
Add the server to the project's .vscode/mcp.json or Claude config and tell the agent to call get_decision_context on files before planning. The rejected record shows up under history. Free; one migrate run and some affects patterns to write.
A staff engineer reviewing an agent-written plan
Check which accepted decisions a proposed change touches
Have the agent list the files the plan changes and call get_decision_context, then get_decision on each governing record to quote its constraints. Pairs with the GitHub Action, which posts the same answer on the pull request.
A consultancy inheriting a client codebase with MADR files
Give agents the client's decision history without building a knowledge base
Run adr migrate --from madr to add adrkit frontmatter in place, then point adrkit-mcp at the repository with --cwd. The original MADR tooling keeps working because the schema is a superset.
Before you commit
- Setup
- npx -y @adrkit/mcp --cwd /path/to/repo --dir docs/adr on Node 22+, or the ghcr.io/mbeacom/adrkit image with mcp and a read-only mount. README configs cover Claude Desktop, VS Code, Cursor and GitHub Copilot CLI. --cwd must be a git worktree root.
- Integrations
- Four read-only tools: search_decisions, get_decision, get_decision_context and list_superseded. Speaks both the 2025 and 2026-07-28 MCP protocol revisions over stdio. The wider project adds a CLI, a pull-request Action, a Spec Kit extension and an agent plugin.
- Data and privacy
- Reads Markdown records under one ADR directory inside one repository, with realpath checks against symlink escapes. No writes, model calls, network access or persistent index, and no port. Record text is input the agent trusts, so treat merge rights to docs/adr accordingly. The separate container REST server has no authentication.
- Cost at scale
- Free under Apache-2.0. Every tools/call reloads the corpus, so cost is local file reads; output pages cap at 100 items.
- Limits
- About 12 open issues. Literal search only; supersession is followed one hop; federated log:id refs are recognised but never resolved; one corpus per server; Copilot CLI plugin hosts cannot launch it.
What’s good
- Surfaces rejected and superseded decisions
- Four read-only tools; no network, model or writes
- Maps files to governing decisions by pattern
- Bounded, paginated output keeps context small
What’s not
- Useless without an adrkit-format ADR corpus
- Literal substring search only, no ranking
- Pre-1.0; the project advises pinning versions
- Each project must wire the server itself
Best for
Teams that already keep architecture decision records in git and want coding agents to check them before proposing a design.
adrkit MCP alternatives
adrkit MCP: common questions
- Is adrkit MCP worth it?
- A small, strictly read-only server that does one thing well, warning an agent off a path the team already rejected, provided your decisions are written down in adrkit's format. We rate it 3.6 out of 5.
- How much does adrkit MCP cost?
- Free and open source (Apache-2.0; the schema is also CC0). No hosted service or paid tier.
- What are the downsides of adrkit MCP?
- Useless without an adrkit-format ADR corpus; literal substring search only, no ranking; pre-1.0; the project advises pinning versions; each project must wire the server itself.
- Who is adrkit MCP best for?
- Teams that already keep architecture decision records in git and want coding agents to check them before proposing a design.
- How much does adrkit MCP cost for a team or in production?
- Free under Apache-2.0. Every tools/call reloads the corpus, so cost is local file reads; output pages cap at 100 items.
- Is adrkit MCP safe for company data?
- Reads Markdown records under one ADR directory inside one repository, with realpath checks against symlink escapes. No writes, model calls, network access or persistent index, and no port. Record text is input the agent trusts, so treat merge rights to docs/adr accordingly. The separate container REST server has no authentication.
- What are the best adrkit MCP alternatives?
- The closest alternatives we have reviewed are MCP Memory Keeper, Memory (reference server) and codebase-memory-mcp.
Answers checked Nov 11, 2026.