Cachly MCP Server

cachly — experience for coding agents (MCP server)

Solve it once. From then on, your AI knows.

Every fix, every decision and every dead end becomes experience your AI uses at the right moment. You build faster, and your team builds on what you figured out.

@cachly-dev/mcp-server connects cachly to Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Continue.dev, Zed, Codex CLI and Gemini CLI over MCP. It offers 124 MCP tools. Your editor lists 27 entries by default and reaches the rest through one of them, cachly_tool (details under MCP Tools below). Your AI stores a lesson after a fix, and finds it again when the same problem returns. Your Brain (the store of your lessons) lives on EU servers.

Start without an account

Claude Code

/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

There is no JSON to write, no path to set and no key to copy. Without a key, cachly creates a test Brain on EU servers when the session starts (the plugin hook does it; the first tool call does it if the hook did not). The test Brain has 14 days of the Dev tier. After that it runs on the free tier with the same key.

Check it with claude mcp list. You should see plugin:cachly-brain:cachly … ✔ Connected. claude plugin details shows MCP servers (0) even when the server runs, because it does not count them.

The plugin adds three Claude Code hooks:

Turn on auto-update once: /plugin → Marketplaces → cachly → Enable auto-update. Claude Code leaves it off for marketplaces outside Anthropic's own. The MCP server updates itself on every start, but the hooks come with the plugin and update only with it. If an update is waiting, the first session_start of a session says so in one line.

Keep your test Brain

npx @cachly-dev/mcp-server@latest claim

You sign in once in the browser. The test Brain then moves into your account with all its lessons. Every test key is revoked, and you get a new key that is stored where your editor and hooks look for it. The Brain restarts once, which takes about 20 seconds. If you already have a free Brain, the one-Brain limit of the free tier applies and the move is refused with a message.

Cursor, Windsurf, VS Code, Cline, Continue.dev, Zed

npx @cachly-dev/mcp-server@latest autopilot

autopilot finds the editors you use and writes the MCP config for each. It adds a git hook that learns from your commits and fills your Brain from your git history. You sign in once in the browser (a device code, no password, no credit card), so the Brain belongs to your own account from the start. Restart your editor afterwards.

You can also add the server by hand (see Manual Setup). Without a key, the first tool call creates the same test Brain as in Claude Code.

Already inside Claude, Cursor or Copilot? Paste this to your AI:

Set up cachly for this project. Run: npx @cachly-dev/mcp-server@latest autopilot
Follow the browser sign-in, then restart the editor.

VS Code extension

Install cachly Brain. It creates your Brain on first start, with no account form.

JetBrains plugin

Install Cachly Brain from the JetBrains Marketplace (IntelliJ IDEA, PyCharm, GoLand, WebStorm, Rider). The status bar, the Brain health and the lessons view live in the IDE. The source is at cachly-dev/cachly-intellij. The JetBrains plugin guide shows how Claude Code, Junie and JetBrains AI Assistant get the Brain over MCP.

MCP Registry

The server is listed in the official MCP Registry as io.github.cachly-dev/mcp-server. Clients that browse the registry find it by name. The entry points at this npm package.

Guides

How it works

1. A fix, a decision or a dead end is stored as a lesson: topic, what worked, what failed, severity, file paths, commands and author.
2. At the start of a session, your AI receives a briefing with the last session, open failures and recent lessons.
3. When you ask for something, smart_recall looks up the lessons that match. It combines keyword search (BM25), meaning-based search and the causal graph, in 11 languages.
4. When an error appears, causal_trace walks from the symptom to the cause and to the fix that worked.
5. Before a deploy, brain_predict lists failure patterns from past incidents.
6. A git hook and the CI templates add lessons from commits and from red-to-green runs.
7. Lessons are shared in the team. Each one carries the name of whoever learned it.

To see what your AI would know before you install anything, run npx @cachly-dev/mcp-server@latest demo in a project folder. It reads your git history and prints your fixes, patterns and decisions. Nothing leaves your machine.

Our agreement with you. You can leave and take your data: npx @cachly-dev/mcp-server@latest export writes every lesson to lessons.md (to read) and lessons.jsonl (to reuse). Code excerpts are stored only if you call index_project yourself, and only on your own EU instance. Read what leaves your machine before you decide.

MCP Tools (124 total, 27 listed by default)

Your editor sees 27 entries by default: the daily tools (26 of them) and one dispatcher, cachly_tool. This is on purpose. The full list of 124 costs about 28,000 tokens in every request. The 27 listed entries cost about 8,000. All other tools (98 of them) run through the dispatcher:

cachly_tool(tool: "team_roster")                  run any of them by name
cachly_tool(tool: "team_roster", describe: true)  get its schema first

Nothing is unreachable. The server dispatches by name, so team_roster called directly still works. Set CACHLY_ALLE_WERKZEUGE=1 to list all 124. Set CACHLY_PROFILE=lean to list 8 plus cachly_tool, or CACHLY_PROFILE=recall to list the 3 read-only tools.

Session and lessons (most used)

Team Brain and org knowledge graph

Causal intelligence

Example:

causal_trace(problem="auth breaks after restart")

→ Root: k8s:namespace-terminating
→ Via:  keycloak:jwks-race
→ Fix:  PollUntilContextTimeout 3min

Shareable and public Brains

Knowledge Commons, infrastructure and roadmap

Run health to see what is wired up in your editor. The full catalog is generated from src/tools.ts.

CLI commands

npx @cachly-dev/mcp-server@latest autopilot # One command: signs in, configures every editor, fills the Brain from git
npx @cachly-dev/mcp-server@latest claim     # Move a test Brain into your account, lessons included
npx @cachly-dev/mcp-server@latest demo      # Preview your Brain from git history (no account needed)
npx @cachly-dev/mcp-server@latest bench     # Run the recall benchmark (no sign-in needed)
npx @cachly-dev/mcp-server@latest autosetup # Interactive variant: pick editors yourself
npx @cachly-dev/mcp-server@latest health    # Check token, API, editors and git hook
npx @cachly-dev/mcp-server@latest export    # Write every lesson to lessons.md and lessons.jsonl
npx @cachly-dev/mcp-server@latest digest    # Weekly Brain summary, shareable
npx @cachly-dev/mcp-server@latest share     # Generate a shareable stats card
npx @cachly-dev/mcp-server@latest publish   # Publish your Brain as an importable link (--public)
npx @cachly-dev/mcp-server@latest badge     # Get a live README badge for your Brain
npx @cachly-dev/mcp-server@latest invite    # Invite a teammate to share your Brain
npx @cachly-dev/mcp-server@latest index .   # Index a project's code into the Brain (CI-friendly)
npx @cachly-dev/mcp-server@latest learn-git # Learn lessons from recent git commits

The method behind bench is described in BENCH.md.

Tip: learn from every merged PR. Run learn-git in CI with the cachly-brain-setup GitHub Action and mode: learn. Each merged PR then teaches your Brain.

CI integration

Every CI run is a lesson. A red→green transition is a proven fix, and a green→red one is a known cause. Ready-to-paste templates live in src/ci-integration/:

• GitHub Actions: use cachly-dev/cachly-action. It needs the secrets CACHLY_API_KEY and CACHLY_BRAIN_INSTANCE_ID.
• GitLab CI: copy brain-from-ci-gitlab.yml into your pipeline. It adds two .post jobs (on_success and on_failure) with allow_failure: true. The full GitLab template adds hidden jobs for learn, scan and confirm. Pull it in with include: remote:.
• Anything else: push-ci-outcome.mjs is a standalone Node.js helper with no dependencies. It always exits 0, so your CI never fails because of a Brain push.

Already have months of CI history? The brain_from_ci tool ingests past outcomes in one call, the way brain_from_git ingests commits.

FAQ

Does my AI need to call session_start by hand? No. A session starts on the first tool call and ends when the editor closes.

Can my whole team share one Brain? Yes. Use team_learn and team_recall, or npx @cachly-dev/mcp-server@latest invite teammate@example.com.

Is my code sent to cachly servers? Only if you call index_project yourself. It stores a short excerpt (up to summary_chars, 1200 characters by default) per indexed file, on your own EU instance. Every other tool stores lesson text, commit messages, session summaries and key-value context, but no source code. Storage is in Germany and embeddings are computed in the EU. API traffic passes through Cloudflare, a US company. The EU guide lists every data flow.

What is causal_trace? Given an error, it walks the causal knowledge graph to find the root cause, the intermediate causes and the fix that worked, with its date and commands.

What if I hit the context-window limit mid-session? Call compact_recover. It rebuilds your context from the Crystal, the recent sessions and the registry of work in progress. Usually one tool call is enough.

How do I write lessons my agent finds again? Lead with the decisive fact. The lessons guide shows how, with examples.

Editor support matrix

npx @cachly-dev/mcp-server@latest autopilot detects and configures the editors below. Manual snippets are in Manual Setup.

Which sign-in path each case uses:

Manual Setup

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

Without a key, the first tool call creates a test Brain on EU servers. No sign-up. Run npx @cachly-dev/mcp-server@latest autopilot to use your own account instead.

{
  "mcpServers": {
    "cachly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

{
  "context_servers": {
    "cachly": {
      "command": {
        "path": "npx",
        "args": ["-y", "@cachly-dev/mcp-server@latest"]
      }
    }
  }
}

Self-hosting and bring-your-own embeddings

Embeddings turn text into vectors for the meaning-based search. By default, cachly computes them on its own servers in the EU as soon as you are signed in. Your text goes to a third-party provider only when you name that provider yourself:

Run npx @cachly-dev/mcp-server@latest health to see which provider is active.

Point at your own backend. Every install can talk to a private backend instead of api.cachly.dev:

# One command: run the setup against your self-hosted backend
npx @cachly-dev/mcp-server@latest autopilot --api-url https://cachly.mycorp.internal

# Or without prompts
npx @cachly-dev/mcp-server@latest autosetup \
  --instance-id <uuid> --api-key <cky_live_...> \
  --api-url https://cachly.mycorp.internal

autosetup writes CACHLY_API_URL into the editor config only when it differs from the default cloud. Default installs stay clean, and self-hosted installs keep talking to your backend on every editor start.

Pricing

Current prices and limits are on cachly.dev/pricing.

The free tier needs no credit card.

Environment Variables

Ecosystem and docs

The VS Code extension shows the same Brain in the editor:

• cachly.dev: dashboard and sign-up
• Documentation
• MCP docs
• Release notes
• GitHub Issues: bugs and feature requests

---

Solve it once. From then on, your AI knows.

npx @cachly-dev/mcp-server@latest autopilot