How to Use an MCP Server for Architecture Documentation
AI coding assistants have become indispensable. Claude Code helps you refactor complex systems. Cursor accelerates feature development. GitHub Copilot suggests implementations. But all of these tools share a common blind spot: they don't know your architecture.
When you ask an AI assistant to "add a new endpoint to the User Service," it doesn't know that your User Service communicates with an Auth Service via gRPC, stores data in PostgreSQL, publishes events to Kafka, and has a specific set of security requirements documented in your ADRs. The AI guesses, you correct, and half the productivity gain evaporates.
MCP servers fix this. They give AI assistants structured access to your architecture documentation, turning your system design into a queryable, actionable data source. This guide covers everything you need to know about using an MCP server for architecture documentation -- what MCP is, why it matters, and how to set it up with Archyl.
What Is MCP (Model Context Protocol)?
MCP -- the Model Context Protocol -- is an open standard created by Anthropic for connecting AI assistants to external tools and data sources. It defines a structured way for AI models to discover, invoke, and receive results from external capabilities.
Think of MCP as a universal adapter. Before MCP, every AI assistant had its own proprietary way of integrating with external tools. MCP standardizes this, creating a single protocol that works across different AI assistants.
An MCP server is a service that exposes a set of tools through the MCP protocol. Each tool has a name, a description, input parameters, and output format. When an AI assistant connects to an MCP server, it discovers the available tools and can invoke them as needed during a conversation.
For architecture documentation, this means your architecture model becomes a set of queryable, modifiable tools that any MCP-compatible AI assistant can use. The AI doesn't need to parse files or guess about your system structure -- it can directly query the authoritative source of truth.
Why Architecture Needs MCP
Architecture documentation sits at the intersection of several needs that MCP addresses perfectly.
Context Is Everything for AI-Assisted Development
The quality of AI-generated code is directly proportional to the quality of context the AI has. When an AI assistant understands your architecture -- what services exist, how they communicate, what technologies they use, what constraints apply -- it generates code that fits naturally into your system.
Without architecture context, AI assistants make assumptions. They might suggest a REST API when your service uses gRPC. They might create a direct database connection when your architecture requires going through a service layer. They might propose a synchronous call when your system uses event-driven communication.
MCP gives AI assistants access to the real architecture, eliminating these mismatches.
Architecture Documentation Is Structured Data
Unlike free-form documentation (wikis, Confluence pages, README files), architecture documentation modeled in the C4 framework is inherently structured. Systems contain containers. Containers contain components. Elements have technologies, descriptions, and relationships. ADRs have statuses and affected elements.
This structure maps naturally to MCP tools. Each type of architectural element becomes a queryable entity. Each operation (list, get, create, update) becomes a tool. The AI assistant can navigate the architecture model the same way a developer navigates a file system.
Documentation Should Be Bidirectional
Most documentation tools are read-only from an API perspective. You can view documents, but modifying them requires opening a specific application. MCP enables bidirectional interaction: the AI assistant can both read from and write to the architecture model.
This means an AI assistant can not only query your architecture but also propose modifications -- adding a new component, creating a relationship, drafting an ADR. The developer reviews and approves these changes, but the AI does the mechanical work of updating the documentation.
Archyl's MCP Server: 56 Tools for Architecture
Archyl provides one of the most comprehensive MCP server implementations for architecture documentation. With 56 tools organized across the full scope of architecture modeling, it covers everything from querying the C4 model to managing releases and tracking drift.
Here's an overview of the tool categories.
Querying the C4 Model
The core query tools let the AI assistant explore your architecture at every level:
- list_systems / get_project_c4_model -- Discover all software systems in a project
- list_containers / list_components -- Navigate the C4 hierarchy
- list_relationships -- Understand how elements connect
- get_element_technologies -- See the technology stack of any element
- get_element_owners -- Know who owns what
These tools enable natural-language queries about your architecture. When you ask "What databases does the Order Service depend on?", the AI can list the Order Service's relationships, filter for database containers, and return a precise answer.
Managing Architecture Elements
Write tools let the AI assistant modify the architecture model:
- create_system / update_system / delete_system -- Manage software systems
- create_container / update_container / delete_container -- Manage containers
- create_component / update_component / delete_component -- Manage components
- create_relationship / update_relationship / delete_relationship -- Manage connections
These tools are particularly powerful for keeping documentation current during development. When you add a new service to your codebase, you can ask the AI assistant to add the corresponding container to the architecture model, set its technologies, and create the appropriate relationships -- all without leaving your IDE.
Architecture Decision Records
ADR tools bring decision documentation into the AI workflow:
- list_adrs / get_adr -- Query existing decisions
- create_adr / update_adr -- Create new ADRs or update existing ones
- link_adr_to_element -- Connect decisions to affected elements
When you're discussing a technology choice with your AI assistant, it can check existing ADRs for related decisions, draft a new ADR for the current decision, and link it to the relevant architectural elements.
API Contracts and Event Channels
Integration documentation tools cover service boundaries:
- list_api_contracts / create_api_contract -- Manage API specifications
- list_event_channels / create_event_channel -- Model async communication
- link_api_contract / link_event_channel -- Connect specs to elements
These tools help maintain the connection between architecture and implementation. When you create a new API endpoint, the AI can check whether an API contract exists for that service and suggest updating it.
Documentation and Collaboration
Broader documentation tools support team workflows:
- create_documentation / update_documentation -- Manage project docs
- create_comment / list_comments -- Annotate architecture elements
- list_flows / create_flow -- Document user and system flows
- get_drift_score / compute_drift_score -- Check documentation accuracy
Releases and Metrics
Operational tools connect architecture to delivery:
- create_release / list_releases -- Track deployments
- get_dora_metrics / get_dora_trend -- Measure engineering performance
- list_environments -- Understand deployment targets
Real Examples: MCP in Action
Here are concrete examples of how developers use Archyl's MCP server in their daily workflow.
Example 1: Querying Systems from Claude Code
You're working in Claude Code and need to understand the architecture before making changes:
You: What systems and containers does our project have?
Claude: Let me check your architecture.
[Calls list_systems, then list_containers for each system]
Your project "E-Commerce Platform" has 3 systems:
1. E-Commerce Platform (software_system)
- API Gateway (Go, Kong)
- User Service (Go, PostgreSQL)
- Order Service (Java, PostgreSQL)
- Product Service (Node.js, MongoDB)
- Notification Service (Python, Redis)
- Event Bus (Kafka)
2. Stripe (external_system)
- Payment processing gateway
3. SendGrid (external_system)
- Transactional email service
The AI returns real data from your documented architecture, not a hallucination.
Example 2: Creating Components from Cursor
You're adding a new module to a service and want to document it:
You: I just added a RateLimiter component to the API Gateway.
It uses Redis and the golang.org/x/time/rate library.
Can you add it to our architecture?
Cursor: I'll add that to your C4 model.
[Calls create_component with name="RateLimiter",
container="API Gateway", technologies=["Redis", "Go"]]
[Calls create_relationship from RateLimiter
to the Redis container]
Done. I've added the RateLimiter component to the API Gateway
and created a relationship to your Redis container.
The documentation is updated in seconds, without leaving the IDE.
Example 3: Checking Drift Before a Refactor
Before a major refactoring effort, you want to know how accurate the documentation is:
You: What's our current drift score? Are there any
undocumented services?
Claude: Let me check.
[Calls get_drift_score]
[Calls get_drift_details]
Your drift score is 78/100 (Good).
Issues detected:
- The Search Service is running in production but not
documented in your C4 model
- The Analytics Service has 2 undocumented relationships
to the Data Warehouse
- The API Gateway's technology list is missing "Redis"
(recently added for rate limiting)
Would you like me to fix these issues?
The AI identifies exactly what's out of date and can fix it automatically.
Example 4: Drafting an ADR
During a design discussion about switching from REST to gRPC for internal service communication:
You: We're considering switching internal service communication
from REST to gRPC. Can you draft an ADR and check if we
have any existing decisions about this?
Claude: Let me check existing ADRs first.
[Calls list_adrs]
I found one related ADR:
- ADR-007: "Use REST for all internal APIs" (Status: Accepted)
This was decided 18 months ago.
I'll draft a new ADR to supersede it.
[Calls create_adr with title="Migrate Internal
Communication from REST to gRPC"]
Created ADR-015 with:
- Context: Current REST-based communication adds
serialization overhead...
- Decision: Adopt gRPC with Protocol Buffers for all
new internal service communication...
- Status: Proposed
- Supersedes: ADR-007
Would you like me to link this to the affected services?
The AI checks for related decisions, drafts a new ADR, and offers to link it to the relevant architecture elements.
Example 5: Understanding Impact Before Changes
Before modifying a service, you want to understand the blast radius:
You: I need to change the Order Service's database schema.
What else depends on the Order Service?
Claude: Let me trace the dependencies.
[Calls list_relationships filtered by Order Service]
[Calls get_element_owners for dependent elements]
The Order Service has these dependents:
- API Gateway -> Order Service (REST, order management)
- Order Service -> Payment Service (gRPC, payment processing)
- Order Service -> Event Bus (publishes OrderCreated,
OrderUpdated, OrderCancelled events)
- Notification Service consumes Order events from Event Bus
- Analytics Service consumes Order events from Event Bus
Owned by:
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team
Schema changes could affect the Payment Service (direct
dependency) and any consumer of Order events. I'd recommend
coordinating with the Payments Team and Data Team.
Setting Up Archyl's MCP Server
Getting started with Archyl's MCP server takes just a few minutes. Here's how to set it up for the most common AI assistants.
Setup for Claude Code
Add the Archyl MCP server to your Claude Code configuration:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Once configured, Claude Code automatically discovers all 56 tools and can use them in any conversation.
Setup for Cursor
Cursor supports MCP servers through its settings. Add Archyl under the MCP section:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
After adding the configuration, restart Cursor. The Archyl tools appear in the MCP tools list, and Cursor can use them during code generation and refactoring.
Setup for Other MCP-Compatible Tools
Any tool that supports the MCP protocol can connect to Archyl's MCP server. The server exposes a standard MCP endpoint with tool discovery, so compatible clients automatically detect and list the available tools.
API Key Generation
Generate your MCP API key from the Archyl dashboard:
- Navigate to your organization settings
- Go to the API section
- Create a new API key with the appropriate permissions
- Copy the key into your MCP server configuration
We recommend creating separate API keys for different use cases (e.g., one for Claude Code, one for CI/CD) so you can rotate them independently.
Best Practices for MCP-Driven Architecture Documentation
Start with Read-Only
When you first set up the MCP server, start with read-only queries. Get comfortable with the AI assistant's ability to explore your architecture before enabling write operations. This builds confidence in the tool's accuracy and reliability.
Review AI-Generated Changes
When the AI assistant creates or modifies architecture elements, review the changes before considering them final. Archyl's history and version features let you see what changed and roll back if needed. The AI is a powerful assistant, but architectural decisions should always have human oversight.
Combine MCP with Architecture as Code
MCP and architecture as code are complementary. Use MCP for interactive queries and quick updates during development. Use architecture as code (the archyl.yaml file) for authoritative, version-controlled definitions that go through code review. The two approaches reinforce each other.
Use MCP in Code Reviews
During code reviews, ask the AI assistant to check whether the code changes align with the documented architecture. "Does this new API endpoint match the API contract documented for this service?" or "Are these database queries going through the service layer as documented?" The AI can validate code against the architecture model in real time.
Teach Your Team the Available Tools
The biggest barrier to MCP adoption is awareness. Most developers don't realize what questions the AI can answer about their architecture. Share examples, create a cheat sheet of useful queries, and demonstrate MCP workflows in team meetings.
The Future of AI-Driven Architecture Documentation
MCP servers represent a fundamental shift in how teams interact with architecture documentation. Instead of documentation being a passive artifact that developers read (or more often, don't read), it becomes an active participant in the development workflow.
When your AI assistant can query the architecture before generating code, check conformance after changes, and update documentation as the system evolves, the barrier between "working on the system" and "documenting the system" disappears.
Architecture documentation stops being something you maintain separately and becomes something that's woven into every development interaction. Every question you ask the AI, every code change you make, every design discussion you have -- all of them can be informed by and reflected in the architecture model.
This is the future Archyl is building toward. The MCP server is the bridge between AI-powered development and structured architecture documentation. And with 56 tools covering the full scope of architecture modeling, it's comprehensive enough to support any workflow your team needs.
Get started with Archyl's MCP server and give your AI assistant the architecture context it's been missing.