I've been using AI coding assistants daily for over a year now.
Claude Code for complex refactoring, Cursor for quick edits, GitHub Copilot for autocomplete. But there was always a frustrating gap: these tools couldn't see my architecture documentation.
Every time I asked Claude to "add a new endpoint to the payment service," it would guess. It didn't know that our payment service talks to Stripe, uses Redis for caching, and has specific security requirements documented in our ADRs. I'd spend more time correcting the AI than writing code myself.
Today, we're closing that gap. Archyl now exposes a full MCP (Model Context Protocol) server with 56 tools that give AI assistants complete visibility into your architecture.
What is MCP?
Model Context Protocol is Anthropic's open standard for connecting AI assistants to external tools and data sources. Think of it as a universal adapter between LLMs and the systems they need to interact with.
Instead of copy-pasting context into prompts, MCP lets AI assistants directly query your tools. They can read data, take actions, and stay synchronized with your actual systems.
And Archyl's MCP server means your architecture documentation becomes a first-class data source for any AI assistant.
What Can You Do With It?
Here's where it gets exciting. With the Archyl MCP server, your AI assistant can:
Query Your Architecture
Ask natural questions and get real answers:
"Which elements are linked to the Payment Processor system?"
"What containers does the User Service depend on?"
"Show me all systems that interact with our PostgreSQL database"
"What ADRs affect the authentication flow?"
The AI doesn't guess. It queries your actual documented architecture and returns precise, structured information.
Claude Code querying architecture via MCP
Navigate the C4 Model
Your AI understands the full hierarchy:
List all projects in your organization
Drill down from systems to containers to components
Explore relationships and dependencies
Understand the technology stack at each level
When you ask "what technologies does the Order Service use?", the AI returns the actual documented stack, not a hallucinated guess.
Modify Documentation
This is the killer feature. The MCP server supports write operations:
Create new systems, containers, and components
Add relationships between elements
Create and update ADRs
Write project documentation
Define user flows
Ask Claude to "document the new notification service we just built" and it can create the C4 elements, link them to existing systems, and even draft an ADR explaining the design decision.
Stay in Sync
The AI always sees the latest state. No stale context, no outdated documentation. When your teammate updates the architecture, your AI assistant sees it immediately.
56 Tools, One Integration
We didn't build a minimal proof-of-concept. The MCP server exposes comprehensive functionality:
Projects & Settings: List, get, and manage projects. Configure AI providers and discovery settings.
C4 Model (All 4 Levels): Full CRUD for systems, containers, components, and code elements. Create relationships, manage overlays, handle the complete model hierarchy.
Documentation: Create and update architecture documentation. Link docs to specific C4 elements.
ADRs: Full Architecture Decision Record management. Create, update, list, and link ADRs to the elements they affect.
User Flows: Define and visualize user journeys through your system.
Discovery: Trigger AI-powered architecture discovery on your connected repositories.
Teams: Query team structure and project access.
Every tool returns structured data that AI assistants can reason about. No parsing HTML, no scraping UIs, no brittle integrations.
Getting Started in 2 Minutes
Here's how to connect Claude Code (or any MCP-compatible tool):
Step 1: Create an API Key
Go to your Archyl profile, click on "API Keys", and create a new key. Give it a descriptive name like "Claude Code" and select the scopes you need (read-only or full access).
Copy the key immediately — you won't see it again.
Step 2: Configure Your MCP Client
Add Archyl to your MCP configuration. For Claude Code, add this to your settings:
{
"mcpServers": {
"archyl": {
"url": "https://api.archyl.com/mcp",
"transport": "http",
"headers": {
"X-API-Key": "your_api_key_here"
}
}
}
}
Step 3: Start Talking to Your Architecture
That's it. Ask your AI assistant about your architecture and watch it fetch real data from Archyl.
Try these prompts:
"List all my Archyl projects"
"What systems exist in the E-commerce Platform project?"
"Show me the relationships for the Payment Gateway"
"Create a new ADR explaining why we chose PostgreSQL"
Why This Matters
Architecture documentation has always had a discoverability problem. You write it, it lives in a wiki or a diagram somewhere, and then nobody reads it. Engineers ask questions in Slack instead of checking the docs.
MCP changes the interaction model. Documentation isn't something you go read — it's something your AI assistant knows. When you ask "how does payment processing work?", the answer comes from your actual architecture, not the AI's training data.
This has profound implications:
Onboarding becomes instant. New engineers ask their AI about system architecture and get accurate answers from day one.
Context is always available. When writing code, the AI knows exactly what services exist, how they connect, and what decisions shaped them.
Documentation stays current. Because it's actively used, inaccuracies get noticed and fixed. Dead documentation is documentation nobody reads.
AI suggestions are grounded. When Claude suggests a design, it's informed by your actual architecture, not generic patterns.
The Bigger Picture
We're entering an era where AI assistants are genuine collaborators in software development. But they're only as good as the context they have access to.
Most AI interactions today are context-poor. You paste some code, add a brief description, and hope the AI figures out the rest. The results are mediocre because the AI is working blind.
MCP-powered integrations flip this model. Your AI has persistent, queryable access to everything it needs: your code (via repository integration), your architecture (via Archyl), your issues (via Jira/Linear integrations), your documentation (via Notion/Confluence integrations).
The AI becomes a true team member with access to team knowledge.
Archyl's MCP server is our contribution to this vision. Your architecture shouldn't be locked in a diagram tool. It should be accessible to every tool your team uses, including your AI assistants.
What's Next
This is version 1. Here's what we're building next:
Proactive suggestions: The MCP server could watch for architecture changes and suggest documentation updates.
Cross-reference linking: Connect ADRs to specific commits, link documentation to CI/CD events, create a web of interconnected knowledge.
Custom queries: Define organization-specific queries like "show me all services owned by the payments team."
Audit logging: Track every MCP interaction for compliance and debugging.
Try It Now
The MCP server is available today on all Archyl plans. If you're already using Claude Code, Cursor, or another MCP-compatible tool, you can connect in minutes.
Create an API key, add the configuration, and start talking to your architecture.
And if you're not using Archyl yet, sign up for free and see how AI-powered architecture documentation works. Connect a repository, run discovery, and then connect your favorite AI assistant.
Your architecture is too important to be locked in static diagrams. Let your AI assistants explore it.
Want to learn more about Archyl's AI capabilities? Check out our post on AI-Powered Architecture Discovery, or start with the basics in our Introduction to the C4 Model.
Top comments (0)