MCP Runner

@leoustc/mcp-runner turns a computer or server into an MCP-based multiple-agent runner.

Install

npm install -g @leoustc/mcp-runner

Commands

mcp-runner login
mcp-runner login codex
mcp-runner serve
mcp-runner serve --port 8000

• serve without --port starts an MCP stdio server.
• serve --port 8000 starts an HTTP Stream MCP server at http://127.0.0.1:8000/mcp.

Storage

Default root directory:

~/.mcp-runner/

Important paths:

~/.mcp-runner/config
~/.mcp-runner/agents/<agent_name>
~/.mcp-runner/projects/<project_key>

Config

~/.mcp-runner/config is JSON and is loaded every time the plan tool is called.

Example:

{
  "user_id": "li",
  "default_agent": "architect",
  "agents": {
    "architect": {
      "command": "codex"
    }
  },
  "projects": {
    "example-project": {
      "workdir": "~/project/example"
    }
  }
}

MCP tools

plan

Default planning entry point.

Input:

{
  "user_id": "li",
  "project_id": "example-project",
  "agent": "architect",
  "content": "plan this task"
}

Current first implementation behavior:

1. Load ~/.mcp-runner/config every call.
2. Check user_id matches this runner config.
3. Check project_id exists.
4. Check requested agent exists.
5. Return an accepted planning response. Actual agent execution/routing is a later step.

action

Alias of plan.

status

Reads config/project/agent state.

check

Alias of status.