Munk AI · MCP Setup

Munk AI exposes its MCP surface from the local munk serve process.

Start Munk AI

Start Munk AI first:

munk serve --host 127.0.0.1 --port 16888

Available endpoints

Munk AI currently exposes two HTTP MCP endpoints from the same local munk serve process:

http://127.0.0.1:16888/mcp
http://127.0.0.1:16888/mcp/device

/mcp: handoff / orchestration workflows such as doctor, plan_create, verify_change, review, run_plan, runs_list
/mcp/device: interactive device control such as devices_list, session_start, session_observe, session_act, session_finalize

If you are only configuring one MCP server for the first time, start with /mcp.

Important transport distinction

There are two common MCP setup patterns:

HTTP MCP: your IDE connects to an already running MCP endpoint
stdio MCP: your IDE starts a local process for you and talks over stdin/stdout

For Munk AI today, the recommended path is HTTP MCP, not stdio MCP.

That means:

your IDE connects to http://127.0.0.1:16888/mcp
your IDE does not start munk serve for you through that HTTP config
you should start munk serve yourself before using the tools

If you want an always-on setup, run munk serve in a dedicated terminal, background process, or local service manager.

What you get after connecting

Once connected, your agent can use Munk AI tools from whichever endpoint you configured:

/mcp: handoff tools for planning, review, verification, and run inspection
/mcp/device: turn-based device tools for observe / act interactive control

Cursor

Cursor supports MCP servers through the UI and through mcp.json.

Option 1: Project-level config

Create .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

This is the best option when you want teammates to share the same local Munk AI setup.

If you also want the interactive device loop, you can add a second entry:

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    },
    "munk-device-control": {
      "url": "http://127.0.0.1:16888/mcp/device"
    }
  }
}

Option 2: Global config

Create ~/.cursor/mcp.json:

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

Use this when you want Munk AI available across all local projects.

Notes for Cursor

Restart or reload Cursor if the server does not appear immediately.
The HTTP config only connects to Munk AI. It does not launch munk serve.
If you add both endpoints, use clear names like munk-handoff and munk-device-control so the agent can distinguish them more easily.
If you want the agent to invoke tools without asking each time, configure Cursor's tool approval and auto-run settings separately.

Trae

Trae supports MCP through its MCP settings page and through project-level JSON config.

Option 1: Add it in the UI

In Trae:

Open Settings
Go to MCP
Click Add > Add Manually
Paste this JSON

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

If you also want the interactive device endpoint, use:

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    },
    "munk-device-control": {
      "url": "http://127.0.0.1:16888/mcp/device"
    }
  }
}

Option 2: Project-level config

Create .trae/mcp.json in your workspace:

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

Then enable project MCP in Settings > MCP.

Notes for Trae

Trae can automatically load project MCP config from .trae/mcp.json once project MCP is enabled.
Trae's MCP auto-run setting controls whether the agent can invoke MCP tools automatically after the server is connected.
If you configure both endpoints, use separate names so the tool chooser can reflect the workflow boundary.
That auto-run setting does not replace starting munk serve itself.

Claude Code

Claude Code can add Munk AI directly from the CLI.

Project-scoped setup

Run:

claude mcp add --scope project --transport http munk-handoff http://127.0.0.1:16888/mcp

For the interactive device endpoint, add another server:

claude mcp add --scope project --transport http munk-device-control http://127.0.0.1:16888/mcp/device

User-scoped setup

Run:

claude mcp add --scope user --transport http munk-handoff http://127.0.0.1:16888/mcp

And optionally:

claude mcp add --scope user --transport http munk-device-control http://127.0.0.1:16888/mcp/device

Verify the server

Run:

claude mcp list

You should see munk-handoff and, if added, munk-device-control in the configured server list.

Notes for Claude Code

The http transport connects Claude Code to an existing Munk AI endpoint.
It does not auto-start munk serve.
If you no longer need one of them, remove it with claude mcp remove munk-handoff or claude mcp remove munk-device-control.

Does the IDE auto-start Munk AI?

Not with the recommended Munk AI setup.

Because Munk AI currently recommends HTTP MCP, the IDE connects to an already running server. In practice:

Cursor connects to the URL from mcp.json
Trae connects to the URL from UI config or .trae/mcp.json
Claude Code connects to the URL you register with claude mcp add --transport http

So the common pattern is:

Start munk serve
Open your IDE or CLI agent
Let the agent use Munk AI tools over MCP

Troubleshooting

If the server does not appear or tools do not work, check these first:

munk serve is still running
you did not start it with --disable-mcp
the MCP URL is exactly http://127.0.0.1:16888/mcp or http://127.0.0.1:16888/mcp/device
your IDE reloaded the latest MCP config
the agent has MCP tools enabled

Recommended next steps

After the connection is working, try a small prompt such as:

"Use Munk AI to run doctor."
"List the apps available in Munk AI."
"Create a verification plan for this code change with verify_change."
"Start a device session with /mcp/device, observe the current screen, and click the primary action."

You can also continue with Interfaces and Entry Points if you want a broader view of how CLI, MCP, GUI, and Local API fit together.