@usecomposer/mcp

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

Links

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

License

MIT