Composer logo

Composer MCP Server

Give your AI coding agent an architecture canvas.
Connect your repo, build architecture diagrams through your coding agent, and keep them linked to real code.

Why

AI coding agents see files, not architecture. They make locally reasonable changes that break the system because they have no understanding of how components connect. Composer gives them that understanding: a structured, visual architecture graph they can read before every change and update as they build.

Composer is a visual system design tool that lets AI coding agents create and modify interactive architecture diagrams through MCP (Model Context Protocol). Your agent gets tools to add services, databases, queues, and connections, and you get a live canvas at usecomposer.com that updates in real-time.

Your IDE  <-->  MCP Server (this package)  <-->  Composer API  <-->  Your Diagram

Quick Start

Claude Code (one command)

claude mcp add --transport http composer \
  https://mcp.usecomposer.com \
  --header "Authorization: Bearer fl_your_token_here"

Replace fl_your_token_here with your token from usecomposer.com > Diagram Settings > MCP Tokens.

Get a token

Sign up at usecomposer.com
Create a diagram
Open Diagram Settings (gear icon) > MCP Tokens > Generate Token
Copy the token (starts with fl_)

Other editors

Claude Code (.mcp.json)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "composer": {
      "type": "http",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

Verify: run /mcp in your Claude Code session. Composer should appear with its tools.

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "composer": {
      "type": "http",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. Look for the MCP tools icon in the chat input.

Codex

One-liner:

codex mcp add composer -- npx -y @usecomposer/mcp --stdio

Or add to ~/.codex/config.toml (or .codex/config.toml in your project root):

[mcp_servers.composer]
command = "npx"
args = ["-y", "@usecomposer/mcp", "--stdio"]

[mcp_servers.composer.env]
COMPOSER_TOKEN = "fl_your_token_here"

Verify: run /mcp in a Codex session to confirm Composer appears.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "composer": {
      "type": "http",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

Open Cursor Settings > MCP section to verify "Composer" appears.

VS Code (Copilot Chat)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "composer": {
      "type": "http",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

VS Code (Cline)

Open Cline sidebar > Settings (gear icon) > MCP Servers > Add Remote Server:

{
  "mcpServers": {
    "composer": {
      "type": "http",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

VS Code (Continue)

Add to .continue/config.yaml:

mcpServers:
  - name: composer
    url: https://mcp.usecomposer.com
    headers:
      Authorization: "Bearer fl_your_token_here"

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json (global config):

{
  "mcpServers": {
    "composer": {
      "serverUrl": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

Note: Windsurf uses "serverUrl" instead of "url".

Restart Windsurf after saving.

OpenCode

Create opencode.json in your project root:

{
  "mcp": {
    "composer": {
      "type": "remote",
      "url": "https://mcp.usecomposer.com",
      "headers": {
        "Authorization": "Bearer fl_your_token_here"
      }
    }
  }
}

Run /mcp to verify Composer appears.

Example Prompts

Once connected, try asking your AI agent:

Prompt	What it does
"Use Composer to import this codebase as an architecture diagram"	Scans your repo and builds the diagram
"Add a Redis cache between the API and the database in Composer"	Adds a new node and edges to the diagram
"Use the Composer MCP to show me the current architecture"	Renders an interactive viewer inline (MCP Apps)
"Run verify_diagram on my Composer diagram"	Checks for missing endpoints, orphaned nodes, etc.
"Use Composer to define the REST API for the user service"	Adds endpoint definitions to a backend node
"Link each Composer node to its source code"	Associates diagram nodes with file paths

Tools

Tool	Description
`get_graph`	Get the full architecture diagram, all nodes and edges
`get_node`	Get details for a single node including connected edges
`search_graph`	Search nodes and edges by keyword
`get_screenshot`	Get a PNG thumbnail of the diagram from the last auto-save
`show_diagram`	Display an interactive diagram viewer inline (MCP Apps)
`upsert_node`	Create or update a node (service, database, queue, etc.)
`upsert_edge`	Create or update a connection between two nodes
`define_api`	Define API endpoints on a backend service node
`delete_element`	Delete a node or edge from the diagram
`link_path`	Link a node to a file or folder in your codebase
`verify_diagram`	Check for issues like missing endpoints or orphaned nodes
`plan_import`	Step-by-step workflow for importing an existing codebase
`get_guide`	Reference guide for node types, protocols, and best practices

Node types: client · frontend · backend · database · cache · queue · storage · external

Edge protocols: REST · gRPC · GraphQL · WebSocket · TCP · UDP · async · event · internal

MCP App Viewer

When used with clients that support MCP Apps (like Claude), the show_diagram tool renders an interactive diagram viewer directly in the conversation. Click nodes, inspect endpoints, and see the full architecture inline. No browser tab needed.

How It Works

This MCP server is a thin client. It authenticates with your token and proxies tool calls to the Composer API at mcp.usecomposer.com. Your diagram data lives on Composer's servers. The MCP server itself is stateless.

Changes made through MCP are immediately visible on the Composer canvas via real-time WebSocket sync. Changes made on the Composer canvas are also visible to your agent on the next tool call. Edits flow both directions.

Demo Mode

Want to explore before signing up? Run the server with sample data:

npx @usecomposer/mcp --demo

This starts the server with a pre-built architecture diagram so you can try all the tools without an account.

Development

git clone https://github.com/olivergrabner/composer-mcp
cd composer-mcp
npm install
npm run dev        # Watch mode (rebuilds on change)
npm run build      # Production build

License

MIT

@usecomposer/mcp

Quick Install