MCP Server - Archyl Docs

Connect AI assistants like Claude, Cursor, and VS Code to your architecture documentation

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:

  • List and browse your projects
  • Create and modify architecture elements
  • Generate documentation
  • Answer questions about your architecture

Supported Tools

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

The MCP server requires an API key for authentication. 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.

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"
      }
    }
  }
}
  1. 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"
    }
  }
}
  1. 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"
    }
  }
}
  1. 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.

Available Tools

Once connected, your AI assistant can use these tools:

Project Management

Tool Description
list_projects List all your projects
get_project Get project details
create_project Create a new project

Architecture Elements

Tool Description
list_systems List systems in a project
create_system Create a new system
list_containers List containers in a system
create_container Create a new container
list_components List components in a container
create_component Create a new component

Relationships

Tool Description
list_relationships List relationships
create_relationship Create a relationship

Documentation

Tool Description
list_adrs List Architecture Decision Records
create_adr Create a new ADR
list_docs List documentation
create_doc Create documentation

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..."

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
  • Check that your API key has the required permissions

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