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 worksCopy Anchor Link

dmx exposes two kinds of MCP primitives:

• Prompts: every workflow skill (like /dmx/plan or /dmx/validate) is registered as an MCP prompt — this is the mechanism that surfaces them as slash commands in your IDE
• Tools: the agent calls these directly rather than you invoking them as commands
  • run_loop, loop_advance, loop_continue, and loop_status drive the loop orchestration
  • get_skill_definition loads a skill's instructions, and list_skills lists the custom and shared skills in the repo
  • snapshot_loop_for_pr marks the Release Loop's run complete before create-pr commits
  • sync_shared_sources does the cloning and copying behind /dmx/sync
  • detect_invoking_ide and setup_ide_rules write the rule files for /dmx/init and /dmx/upgrade

list_skills isn't the same as the dmx list-skills command-line command. The command-line version prints the skills bundled with dmx; the tool lists the skills in your repo and its shared sources.

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

Transport modesCopy Anchor Link

dmx supports two transports:

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

Add dmx to your IDECopy Anchor Link

Every IDE uses the same config:

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

Save it to the file for your IDE:

Project files live at the repo root, so commit them and every developer gets dmx without setting it up. Claude Code and VS Code both read the same .mcp.json, so one file covers both. If a file already exists, add the dmx entry to its mcpServers object.

Then:

• Cursor: restart Cursor.
• Claude Code: the first time you open a project with a shared .mcp.json, Claude Code asks you to approve its servers. Run claude mcp list to confirm dmx is connected.
  • Desktop app: claude_desktop_config.json applies to the app's Code tab and to Claude Desktop chat, in every project. On Windows it's %APPDATA%\Claude\claude_desktop_config.json. Restart the app after saving.
  • Terminal and IDE extensions: the claude CLI doesn't read claude_desktop_config.json. It keeps per-user servers in ~/.claude.json alongside its own state, so for all your projects add dmx with claude mcp add --scope user dmx -- uvx --from deepmodel-dmx@latest dmx serve rather than editing that file. If dmx is already in your desktop config, claude mcp add-from-claude-desktop copies it over (macOS and WSL).
• VS Code: if you already use .vscode/mcp.json, you can add dmx there instead. That file uses a top-level servers key instead of mcpServers.

To pin every developer to one release, replace @latest with an exact version, such as deepmodel-dmx==0.5.0. See Upgrading dmx.

Deploy to every machineCopy Anchor Link

To roll dmx out with Jamf, Intune, or another MDM tool, see Enterprise Deployment. It covers the per-user config files, Claude Code's managed-mcp.json, network and mirror settings, and a tested Jamf Pro policy script.

Other MCP-compatible IDEsCopy Anchor Link

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

uvx --from deepmodel-dmx@latest dmx serve

dmx works out the workspace root on every tool call. See Workspace root below.

HTTP + SSE transportCopy Anchor Link

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.

Verifying the connectionCopy Anchor Link

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 scopeCopy Anchor Link

By default, dmx reads .dmx/ from the current workspace root. 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.

Workspace rootCopy Anchor Link

dmx resolves the workspace root again on every tool call, in this order:

1. Explicit workspace_root: a path the agent passes to the tool. Must be absolute (~ is expanded); a relative path is rejected.
2. MCP roots: the first workspace root your IDE reports to the server.
3. Server working directory: the directory the dmx process was started in, as a last resort.

dmx checks the result before using it. A filesystem root or your home directory is always rejected. An auto-detected root (2 or 3) must also contain a .git or .dmx directory. If it doesn't, the call fails with an error instead of guessing, so loop state is never written outside your project. The exception is the /dmx/init bootstrap, which works on a brand-new project that has neither yet.

If you see an error like this:

no `.git` or `.dmx` found here — this doesn't look like a project root.

your IDE probably opened a parent folder, or doesn't report MCP roots and started dmx somewhere else. Open the repository root itself in your IDE, or ask the agent to retry with workspace_root set to the project's absolute path.