Zügel MCP Server

AI amplifies what it finds

Software architecture is not the strongest feature of AI coding agents. They are trained to optimize locally and never consider the big picture when implementing a task. That leads to architectural erosion, which makes the code harder to understand and maintain.

A recent Stanford study measured the productivity gains from AI usage for 120 thousand developers. The average gain was only about 10%, but the outcomes differed dramatically between teams: some more than doubled their productivity while AI actually slowed others down. The best predictor of a positive outcome was the cleanliness of the codebase the agent worked with. Cleaner, well-structured codebases lead to better results; messy codebases lead to messier results.

Prevention is Zügel's most important contribution

The idea is simple: help the coding agent respect your architectural intent and avoid adding cyclic dependencies. Those two are the pillars of any well-architected codebase. Without such constraints it is almost certain that generated code loses architectural cohesion over time and introduces more and more tangles, especially when several people work with agents on the same codebase. Once structural erosion kicks in, it creates a self-reinforcing loop that accelerates the deterioration.

Every time the agent wants to add a new dependency it can ask Zügel whether that dependency respects the architecture and does not create or enlarge cyclic dependency groups. If the reply is negative, Zügel helps find a correct alternative. Prevention happens at the earliest possible moment, even before the agent generates code. No need to wait for a CI build to find out that something is wrong.

• Just by running Zügel with your agent you have a guarantee that the structure of your project will not end up as a big ball of mud.
• If you have defined an architectural model using our architecture DSL (domain specific language), all generated code respects the architecture as well.
• You can create the architecture using prompts. Zügel teaches the architecture DSL to the agent, so you can just say "Create a layered architecture split into domains" and the agent creates the DSL file and uses it to verify new dependencies.
• Zügel keeps a ledger of its prevention work, so you can ask the agent about the contributions of its sidekick.
• Your project data never leave the machine Zügel is running on.

Disentangle legacy codebases

Since Zügel keeps a complete dependency model of your application in memory (currently supporting Java, C# and Python) it can also propose refactorings that improve the structure of your application. That is valuable for any legacy codebase, and many of them turned into a big ball of mud over the years. Using clever graph algorithms, Zügel computes optimal breakup sets for cyclic dependencies on the file and directory/package/namespace level. That works even without an architectural model, based purely on the shape of the dependency graph. Add an architectural model and the breakup analyzer takes your architecture into account, which produces even better results.

We tested that on the open source project jPOS. The version checked out in August 2026 had a component (file) cyclicity of 1,147 and a package/directory cyclicity of 361. In just one afternoon with Claude and Zügel we reduced both without breaking a single test. That afternoon would not have been necessary if Zügel had been used on jPOS from the beginning.

On the fly we also created a basic architectural model for the existing code, and that turned out to be the turning point rather than a detour. Package structure barely moved while Zügel had only the shape of the dependency graph to go on. Once the architecture was declared, it could nominate cuts from your rules instead, and the final step of the exercise was the cheapest since that work began, as well as the one that improved the package structure the most. An architecture definition is not overhead you pay before the work — it is what makes the work cheap.

If you need to break up a big ball of mud or modernize a legacy codebase, Zügel tells you something your build cannot. All 4,437 jPOS tests were green at every checkpoint of that afternoon, including at the very start, at a cyclicity of 1,147. A passing build tells you the code still works. It tells you nothing about whether the structure just got worse, and by the time anyone notices, the cheap moment to fix it has passed.

Fix your existing architecture violations

Once you have an architectural model, Zügel knows all the places in the code where a dependency violates your architecture rules, and you can simply delegate the fixing to your coding agent. That delegation works because the agent is not asked for judgment it does not have: your rules already say which dependencies are legal, so Zügel can hand it the permitted alternatives together with the problem. Finding violations is not new — Sonargraph has done it for two decades. What is new is that the list is in your agent's hands while it works, and that it is refreshed on every change.

Fixing violations does more than tidy up the rule book. On jPOS it was what broke the remaining tangle: once the architecture had been declared, Zügel reported that the surviving 16-package cycle could be broken by fixing violations alone, with no further cuts at all. The two repairs taken from that list produced the largest package improvement of the whole exercise. Structure and rules are not two separate problems — repairing the second is often how you repair the first.

We build Zügel with Zügel

Zügel's own source code is governed by Zügel. Its architecture is defined in an architecture DSL file, and the agent working on the server has to ask permission for every new dependency, exactly like the agent working on your code. At the time of writing that leaves the project at zero architecture violations, no component cycles and no package cycles at all — not as a cleanup we once did, but as a state neither we nor our agents are allowed to leave.

The product also improves where it is used. The jPOS afternoon produced eight Zügel releases while it was still running, every one of them from a gap we hit doing the actual work — the single most useful piece of information the tool offered during that exercise did not exist when the exercise started. Taking a real legacy codebase apart with the tool is how the tool gets built.

Zügel and Sonargraph

Think of Zügel as the Sonargraph-Architect for the coding agent. You can use Zügel completely independently of Sonargraph, but if you already have Sonargraph-Architect you get one Zügel license per Sonargraph-Architect license for free. If your project is already set up for Sonargraph-Architect, you can generate Zügel's configuration file directly from Sonargraph; your active architecture definitions are added to the Zügel configuration automatically.

Using them together gives you additional benefits:

• Architecture checks via Sonargraph-Build.
• An editor for the architecture DSL with error checks and autocompletion.
• Powerful dependency visualizations.