Sub Agents MCP Server

by shinprio.github.shinpr/sub-agents-mcpv0.14.2

MCP server for delegating tasks to specialized AI assistants in Cursor, Claude Code, Codex, Command Code, Google Antigravity, Gemini, GLM, Kimi, Grok, and OpenCode

98Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active11d ago

Install Sub Agents MCP server

claude mcp add sub-agents -e AGENTS_DIR='<agents-dir>' -e AGENT_TYPE='<agent-type>' -e CURSOR_API_KEY='<cursor-api-key>' -e CLI_API_KEY='<cli-api-key>' -- npx -y sub-agents-mcp

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": [
        "-y",
        "sub-agents-mcp"
      ],
      "env": {
        "AGENTS_DIR": "<agents-dir>",
        "AGENT_TYPE": "<agent-type>",
        "CURSOR_API_KEY": "<cursor-api-key>",
        "CLI_API_KEY": "<cli-api-key>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": [
        "-y",
        "sub-agents-mcp"
      ],
      "env": {
        "AGENTS_DIR": "<agents-dir>",
        "AGENT_TYPE": "<agent-type>",
        "CURSOR_API_KEY": "<cursor-api-key>",
        "CLI_API_KEY": "<cli-api-key>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "sub-agents": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "sub-agents-mcp"
      ],
      "env": {
        "AGENTS_DIR": "<agents-dir>",
        "AGENT_TYPE": "<agent-type>",
        "CURSOR_API_KEY": "<cursor-api-key>",
        "CLI_API_KEY": "<cli-api-key>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": [
        "-y",
        "sub-agents-mcp"
      ],
      "env": {
        "AGENTS_DIR": "<agents-dir>",
        "AGENT_TYPE": "<agent-type>",
        "CURSOR_API_KEY": "<cursor-api-key>",
        "CLI_API_KEY": "<cli-api-key>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
AGENTS_DIR	yes	—	Absolute path to the directory containing agent definition files (.md or .txt)
AGENT_TYPE	yes	—	Type of AI CLI to use: 'cursor', 'claude', 'gemini', 'codex', 'command-code', 'glm', 'kimi', 'grok', 'antigravity', or 'opencode'
AGENT_PERMISSION	—	—	Approval/sandbox level for sub-agents: 'read-only', 'safe-edit' (default), or 'yolo'
AGENT_MODEL	—	—	Optional model override applied to every sub-agent execution by this MCP server
AGENT_EFFORT	—	—	Optional backend-specific reasoning effort or model variant. Supported by codex, claude, command-code, glm, kimi, grok, antigravity, and opencode.
CURSOR_API_KEY	—	yes	API key for cursor-agent authentication (used only when AGENT_TYPE=cursor; passed via env, never via CLI args)
CLI_API_KEY	—	yes	Provider API key for AGENT_TYPE=glm or kimi (passed to the claude binary via env, never via CLI args). Restart/reconnect the MCP server after changing it.
EXECUTION_TIMEOUT_MS	—	—	Agent execution timeout in milliseconds, as a positive whole number (default: 300000). The server refuses to start on an invalid value such as "5min".
SESSION_ENABLED	—	—	Enable session management to maintain execution history across agent calls (default: false)
SESSION_DIR	—	—	Directory path for storing session files (default: .mcp-sessions in current working directory)
SESSION_RETENTION_DAYS	—	—	Number of days to retain session history before automatic cleanup (default: 1)
AGENTS_SETTINGS_PATH	—	—	Path to CLI settings file/directory. Claude: --settings arg, Cursor: CURSOR_CONFIG_DIR, Codex: CODEX_HOME. GLM/Kimi/Gemini/Grok/Antigravity/OpenCode/Command Code not supported.

Freshness

Active — last maintenance signal 11d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-09-29 · 11d ago · GitHub
Latest release
2026-09-06 · 34d ago · GitHub · v0.14.2
Package published
no data · npm/PyPI
Registry entry updated
2026-09-06 · 34d ago · official registry · v0.14.2

FAQ

›How do I install the Sub Agents MCP server in Claude Code?

Run: claude mcp add sub-agents -e AGENTS_DIR='<agents-dir>' -e AGENT_TYPE='<agent-type>' -e CURSOR_API_KEY='<cursor-api-key>' -e CLI_API_KEY='<cli-api-key>' -- npx -y sub-agents-mcp. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Sub Agents require an API key?

Yes. It expects AGENTS_DIR, AGENT_TYPE, CURSOR_API_KEY, CLI_API_KEY, of which 2 are secrets.

›Can I use Sub Agents as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Sub Agents in the official MCP registry?

Yes, as io.github.shinpr/sub-agents-mcp.