MCP Server

Archyl provides a Model Context Protocol (MCP) server that allows AI assistants to interact with your architecture documentation. This enables powerful AI-powered architecture exploration and documentation.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external tools and data sources. With Archyl's MCP server, your AI assistant can:

• Browse and query your projects and their full C4 model
• Create and modify architecture elements, relationships and diagrams
• Read and write ADRs, documentation, API contracts and event channels
• Check conformance rules, drift scores, DORA metrics and ownership before it writes code
• Track releases, change requests, comments and history

Supported clients

Archyl's MCP server works with:

• Antigravity - Google's AI-powered IDE
• Claude Code - Anthropic's CLI tool
• Claude Desktop - Claude's desktop application
• Cursor - AI-first code editor
• OpenAI Codex - OpenAI's AI coding assistant
• VS Code - With GitHub Copilot Chat
• Warp - Modern terminal with AI integration
• Windsurf - Codeium's AI-powered IDE

Authentication

API key (recommended)

Most clients authenticate with an API key. Depending on the tool you're using:

• Tools with header support (Claude Code, Cursor, Warp, Windsurf, Antigravity): Use the X-API-Key header
• Tools without header support (Claude Desktop, VS Code, OpenAI Codex): Use the ?apiKey=YOUR_API_KEY query parameter in the URL

Generate an API key from your Profile → API Keys page.

The key's scopes decide what the assistant can do: a read-only key can call every list_* and get_* tool, while create_*, update_*, delete_* and import_dsl require a key with write scope. Handing your agent a read-only key is the simplest way to let it explore your architecture without being able to change it.

OAuth 2.1

The server also implements OAuth 2.1 with dynamic client registration, for clients that connect through a browser sign-in rather than a pasted key (the mcp:read and mcp:write scopes mirror the API key scopes above). Point such a client at the same endpoint and it will discover the flow automatically through:

https://api.archyl.com/.well-known/oauth-authorization-server
https://api.archyl.com/.well-known/oauth-protected-resource

Setup

Antigravity

1. Open Antigravity and click the "..." menu in the Agent panel
2. Select "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

4. Restart Antigravity to apply changes

Note: Antigravity uses serverUrl instead of url for HTTP-based MCP servers.

Claude Code

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Run Claude Code - it will auto-detect the MCP server.

Claude Desktop

1. Open Claude Desktop settings
2. Navigate to Developer → MCP Servers
3. Click "Add Server" and add:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
    }
  }
}

4. Restart Claude Desktop

Note: Claude Desktop remote connectors don't support custom headers, so the API key must be passed as a URL query parameter.

Cursor

Create a .cursor/mcp.json file in your project:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Cursor to load the MCP server.

OpenAI Codex

Open or create ~/.codex/config.toml and add:

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"

Restart Codex CLI or IDE to apply changes.

VS Code

1. Open VS Code settings (Cmd/Ctrl + ,)
2. Search for "MCP" and click "Edit in settings.json"
3. Add:

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
      }
    }
  }
}

Warp

1. Open Warp and go to Settings > MCP Servers
2. Click "Add Server" and paste the configuration:

{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
}

3. Restart Warp to apply changes

Windsurf

Open the MCP config file at ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Windsurf to apply changes.

Tool reference

The server exposes 189 tools. They follow a predictable naming scheme, so an assistant can usually guess the right one:

Most project-scoped tools take a projectId; element-scoped tools take an elementId plus an elementType (the C4 level: 1 = system, 2 = container, 3 = component, 4 = code). Ask your assistant to call list_projects first — it will pick up the IDs it needs from there.

Your client discovers this list automatically via tools/list, so it is always in sync with the server. The tables below are for humans deciding what to ask for.

Tool profiles

189 tools is more than a coding agent doing a bounded task needs — advertising them all costs context. Append ?profile=coding to the MCP URL (or send an X-Archyl-Tool-Profile: coding header) to narrow the surface to 16 tools: task-scoped context, the harness work-session loop, and the conformance/diff checks. Omit the parameter (or use profile=full) for the complete catalog.

Agent context (4)

Start here: these give an assistant the architecture picture in one call, instead of many.

Harness work sessions (8)

The governed work loop for coding agents: declare a unit of work to get focused context and advisory leases, heartbeat while working, finish with an outcome that can open an Architecture Change Request. Plus project memory: remember facts for future workers, recall what previous sessions learned.

Projects (7)

Organizations & teams (5)

C4 elements (15)

Systems (level 1), containers (level 2), components (level 3) and code elements (level 4).

Relationships (4)

Diagram layout & overlays (5)

Documentation (11)

Architecture Decision Records (6)

API contracts (8)

OpenAPI, gRPC, GraphQL, AsyncAPI and MCP tool contracts.

Event channels (8)

Flows & whiteboards (8)

Comments & discussions (11)

Ownership (6)

Technologies & radar (10)

Releases & environments (10)

Architecture change requests (6)

Conformance rules (9)

Drift detection (4)

DORA metrics, ROI & predictions (4)

History & time travel (5)

Insights (3)

Marketplace & widgets (15)

Webhooks (7)

Organization-wide architecture (9)

Cross-project views and organization-level artifacts.

Architecture as code (1)

Example Conversations

Exploring Architecture

You: "What systems are in my e-commerce project?"

AI: Uses list_systems tool "Your e-commerce project has 4 systems: Web Store, Payment Service, Inventory System, and Notification Service..."

Creating Elements

You: "Add a new container called Redis Cache to the Web Store system for session storage"

AI: Uses create_container tool "I've created the Redis Cache container in the Web Store system with the description 'In-memory cache for session storage'."

Documentation

You: "Create an ADR for our decision to use PostgreSQL over MongoDB"

AI: Uses create_adr tool "I've created ADR-001: Database Technology Selection, documenting the decision to use PostgreSQL for its ACID compliance and query flexibility..."

Before writing code

You: "I'm about to add rate limiting to the checkout flow. What should I know?"

AI: Uses find_relevant_context and impact_of "Checkout touches the API Gateway and the Orders service. Changing the gateway affects 6 downstream containers. ADR-014 already mandates Redis for throttling, and a conformance rule forbids new dependencies on the legacy Session store..."

Governance check

You: "Are we drifting from the documented architecture?"

AI: Uses get_drift_score and run_conformance_check "Drift score is 82% (down from 91% last month). Two violations: the Search service calls the Orders database directly, and Payments uses an unapproved HTTP client..."

Endpoint

Streamable HTTP (MCP)

https://api.archyl.com/mcp

Use this endpoint to connect your AI assistant to Archyl's architecture documentation. It supports the Streamable HTTP transport protocol.

Troubleshooting

Connection Failed

• Check your API key is valid
• Ensure the endpoint URL is correct
• Check your network connection

Authentication Failed

• For tools with header support: Verify the X-API-Key header is set correctly
• For tools without header support: Verify the ?apiKey= query parameter is in the URL
• Ensure your API key hasn't expired

Tool Not Found

• Make sure you're using the correct tool name — see the tool reference, or ask your client to refresh its tool list
• Some clients cache tools/list; restart the client after upgrading

Write Tools Rejected

• create_*, update_*, delete_* and import_dsl need an API key with write scope — a read-only key can only call list_* and get_*
• Check your subscription plan: some features (webhooks, marketplace connections, managed agent runs) are plan-gated

Antigravity-specific Issues

• Make sure you're using serverUrl (not url) for the configuration
• Config location is ~/.gemini/antigravity/mcp_config.json

OpenAI Codex-specific Issues

• Ensure the TOML syntax is correct in ~/.codex/config.toml
• Use [mcp_servers.archyl] as the table name

Warp-specific Issues

• Navigate to Settings > MCP Servers to manage configurations
• Restart Warp after making configuration changes

Best Practices

Be Specific

When asking your AI to modify architecture, be specific:

• Include project names
• Specify element types
• Provide descriptions

Review Changes

Always review AI-created elements:

• Check names and descriptions are accurate
• Verify relationships are correct
• Update as needed

Use for Exploration

MCP is great for:

• Quickly exploring large architectures
• Generating initial documentation
• Answering questions about your systems