@usecomposer/mcp

Composer MCP Server

Give your AI coding agent an architecture canvas.
Design, visualize, and evolve software architecture diagrams - right from your IDE.

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

Try it now - no account needed:

npx @usecomposer/mcp --demo

Starts the server with sample architecture data so you can explore all the tools.

Getting Started

1. 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_)

2. Connect your IDE

Claude Code

One-liner:

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

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

Tools

Read

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)

Write

Tool	Description
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

Plan & Verify

Tool	Description
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

Example Prompts

Once connected, try asking your AI agent:

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

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.

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

Links

• Composer - the visual architecture canvas
• MCP Protocol - Model Context Protocol spec
• Issues - bug reports and feature requests

License

MIT