MCP Server Setup

dmx runs as an MCP (Model Context Protocol) server. You install it once per IDE, and it's available in every project you open.

How it works

dmx exposes two categories of tools through MCP:

• Skill tools: every workflow skill (like /dmx/plan or /dmx/validate) becomes an MCP tool your IDE can invoke
• Loop runtime tools: run_loop, loop_advance, and loop_continue drive the loop orchestration

Your IDE connects to dmx on startup and discovers all available tools automatically.

Transport modes

dmx supports two transports:

Transport	When to use
stdio (default)	Local development. The IDE spawns dmx as a subprocess. Zero config, zero network.
HTTP + SSE	Shared team server or remote development. dmx runs as a persistent server, multiple IDEs connect.

For local development, use stdio. It's the simplest setup and requires no running server.

Cursor

Add to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project directory for project-only scope:

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
    }
  }
}

Restart Cursor after saving.

Claude Code

Add to your Claude desktop config file. On macOS, this is at:
~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
    }
  }
}

Restart Claude Code after saving.

Other MCP-compatible IDEs

For any IDE that supports MCP via stdio, the command is:

uvx --from deepmodel-dmx dmx serve

dmx auto-detects the workspace root from the working directory.

HTTP + SSE transport

To run dmx as a persistent server:

uvx --from deepmodel-dmx dmx serve --http --port 8080

With bearer token authentication:

REQUIRE_API_KEY=true MCP_API_KEY=your-secret-token uvx --from deepmodel-dmx dmx serve --http --port 8080

In your IDE, connect to http://localhost:8080/sse.

For shared team servers, run dmx on a dedicated host and point each developer's IDE at the server URL. Use a different token per developer for auditability.

Custom skills and rules directories

dmx loads skills and rules from two optional directories:

Environment variable	Default	Description
DMX_SKILLS_DIR	(bundled skills only)	Path to a directory of custom skill .md files
DMX_RULES_DIR	(bundled rules only)	Path to a directory of custom rule .md files

Pass them as environment variables when starting dmx:

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx", "dmx", "serve"],
      "env": {
        "DMX_SKILLS_DIR": "/path/to/your/skills",
        "DMX_RULES_DIR": "/path/to/your/rules"
      }
    }
  }
}

Custom skills are merged with the bundled set. If a custom skill has the same name as a bundled skill, the custom one wins.

Verifying the connection

After connecting, ask your IDE: What dmx skills are available?

A working connection returns the full list of dmx skills. If you see no skills or an error, check:

1. uvx is on your PATH (which uvx)
2. Your IDE config file is valid JSON (no trailing commas)
3. Your IDE was restarted after config changes

Project scope vs. global scope

By default, dmx reads .dmx/ from the current workspace directory. You can point multiple projects at the same dmx server. Each project's .dmx/ is isolated.

If you work in monorepos, dmx resolves .dmx/ from the workspace root, which is typically the root of the repository as seen by your IDE.