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)](https://modelcontextprotocol.io). Your agent gets tools to add services, databases, queues, and connections, and you get a live canvas at [usecomposer.com](https://usecomposer.com) that updates in real-time.
```
Your IDE <--> MCP Server (this package) <--> Composer API <--> Your Diagram
```
## Getting Started
### Connect your IDE
**Claude Code:**
```bash
claude mcp add --transport http composer https://mcp.usecomposer.com
```
**Cursor** — create `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"composer": {
"type": "http",
"url": "https://mcp.usecomposer.com"
}
}
}
```
Your browser will open for authorization on first use.
Claude Code
```bash
claude mcp add --transport http composer https://mcp.usecomposer.com
```
Cursor
Create `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"composer": {
"type": "http",
"url": "https://mcp.usecomposer.com"
}
}
}
```
Codex
```bash
codex mcp add composer -- npx -y @usecomposer/mcp --stdio
```
VS Code (Copilot Chat)
Create `.vscode/mcp.json` in your project root:
```json
{
"servers": {
"composer": {
"type": "http",
"url": "https://mcp.usecomposer.com"
}
}
}
```
VS Code (Cline)
Open Cline sidebar > Settings (gear icon) > MCP Servers > Add Remote Server:
```json
{
"mcpServers": {
"composer": {
"type": "http",
"url": "https://mcp.usecomposer.com"
}
}
}
```
VS Code (Continue)
Add to `.continue/config.yaml`:
```yaml
mcpServers:
- name: composer
url: https://mcp.usecomposer.com
```
Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"composer": {
"serverUrl": "https://mcp.usecomposer.com"
}
}
}
```
> **Note:** Windsurf uses `"serverUrl"` instead of `"url"`.
OpenCode
Create `opencode.json` in your project root:
```json
{
"mcp": {
"composer": {
"type": "remote",
"url": "https://mcp.usecomposer.com"
}
}
}
```
## Tools
### Diagram Management
| Tool | Description |
|------|-------------|
| `list_diagrams` | List all your diagrams. Call this first to find which diagram to work on |
| `create_diagram` | Create a new diagram and auto-select it for this session |
| `select_diagram` | Select which diagram to work on for this session |
| `rename_diagram` | Rename the currently selected diagram |
> **Note:** Call `list_diagrams` then `select_diagram` (or `create_diagram`) before using other 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 |
### 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 |
| *"Create a new Composer diagram called Backend Architecture"* | Creates and auto-selects a new diagram |
| *"Add a Redis cache between the API and the database in Composer"* | Adds a new node and edges to the diagram |
| *"Add analytics monitoring to the Composer diagram"* | Adds observability nodes and connections |
| *"Update the APIs I defined in Composer"* | Refreshes endpoint definitions on backend nodes |
| *"Verify my Composer diagram"* | Checks for missing endpoints, orphaned nodes, etc. |
| *"Link each Composer node to its source code"* | Associates diagram nodes with file paths |
## How It Works
Authentication is handled via OAuth 2.1 — your browser opens for a one-time consent flow, and you're connected. Tool calls are proxied 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](https://usecomposer.com) via real-time WebSocket sync.
## Development
```bash
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](https://usecomposer.com) - the visual architecture canvas
- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol spec
- [Issues](https://github.com/olivergrabner/composer-mcp/issues) - bug reports and feature requests
## License
MIT