MCP Goose Subagents Server

An MCP (Model Context Protocol) server that enables AI clients to delegate tasks to autonomous developer teams using Goose CLI subagents.

Features

• Delegate to Subagents: Create specialized AI agents for different development roles

• Parallel & Sequential Execution: Run agents simultaneously or in sequence

• Recipe System: Create reusable agent configurations

• Session Management: Track and retrieve results from active subagent sessions

• Pure Goose CLI Integration: Uses only Goose CLI for subagent delegation

Related MCP server: Claude Team MCP

Prerequisites

1. Goose CLI installed and configured

2. Node.js (v18 through v24; the tested package compatibility bound is >=18 <25)

3. Alpha features enabled for Goose subagents

Installation

npm install

Usage

1. Add to MCP Configuration

Add this server to your MCP client configuration (e.g., mcp_config.json):

{
  "mcpServers": {
    "goose-subagents": {
      "command": "node",
      "args": ["path/to/mcp-goose-subagents/src/index.js"],
      "env": {
        "ALPHA_FEATURES": "true"
      }
    }
  }
}

2. Enable Goose Alpha Features

export ALPHA_FEATURES=true

Available Tools

delegate_to_subagents

Delegate development tasks to specialized Goose subagents.

Parameters:

• task (string): The development task to delegate

• agents (array): Array of subagent configurations

  • role (string): Agent role (e.g., "backend_developer", "frontend_developer")

  • instructions (string): Specific instructions for the agent

  • recipe (string, optional): Recipe name to use

• execution_mode (string): "parallel" or "sequential"

• working_directory (string, optional): Working directory for agents

working_directory must already exist beneath GOOSE_MCP_ROOT (the server's startup directory by default). Relative or absolute paths that resolve inside the root are accepted; traversal and symlinks that resolve outside it are rejected.

Example:

{
  "task": "Build a REST API with authentication",
  "agents": [
    {
      "role": "backend_developer",
      "instructions": "Create Express.js API with JWT authentication"
    },
    {
      "role": "database_engineer", 
      "instructions": "Design and implement user database schema"
    },
    {
      "role": "security_auditor",
      "instructions": "Review authentication implementation for security issues"
    }
  ],
  "execution_mode": "parallel"
}

create_goose_recipe

Create reusable Goose recipes for specialized subagents.

Parameters:

• recipe_name (string): Name of the recipe

• role (string): Agent role

• instructions (string): Detailed instructions

• extensions (array, optional): Goose extensions to enable

• parameters (object, optional): Recipe parameters

list_active_subagents

List currently active subagent sessions and their status.

get_subagent_results

Retrieve results from completed subagent sessions.

Parameters:

• session_id (string): Session ID to get results for

Example Workflows

Autonomous Full-Stack Development

// Delegate a complete web app development task
{
  "task": "Create a todo app with React frontend and Node.js backend",
  "agents": [
    {
      "role": "project_architect",
      "instructions": "Design overall architecture and create project structure"
    },
    {
      "role": "backend_developer", 
      "instructions": "Build REST API with CRUD operations for todos"
    },
    {
      "role": "frontend_developer",
      "instructions": "Create React components and integrate with API"
    },
    {
      "role": "qa_engineer",
      "instructions": "Write tests and ensure quality standards"
    }
  ],
  "execution_mode": "sequential"
}

Parallel Code Review

{
  "task": "Review authentication module for security and performance",
  "agents": [
    {
      "role": "security_auditor",
      "instructions": "Analyze for security vulnerabilities and best practices"
    },
    {
      "role": "performance_reviewer",
      "instructions": "Identify performance bottlenecks and optimization opportunities"  
    },
    {
      "role": "code_quality_reviewer",
      "instructions": "Check code style, maintainability, and documentation"
    }
  ],
  "execution_mode": "parallel"
}

Agent Roles Examples

• backend_developer - API development, server-side logic

• frontend_developer - UI/UX implementation, client-side code

• database_engineer - Schema design, query optimization

• devops_engineer - Deployment, CI/CD, infrastructure

• qa_engineer - Testing, quality assurance

• security_auditor - Security review, vulnerability assessment

• code_reviewer - Code quality, best practices

• documentation_writer - Technical documentation, API docs

• project_architect - System design, architecture planning

Environment Variables

• ALPHA_FEATURES=true - Required for Goose subagents

• GOOSE_RECIPE_PATH - Path to custom recipe directory

• GOOSE_MCP_ROOT - Trusted workspace root. Defaults to the server startup directory.

• GOOSE_MCP_TIMEOUT_MS - Goose process timeout in milliseconds (default 15 minutes, capped at 1 hour).

Security boundary

Tool arguments are model-controlled. This server constrains Goose's working directory and generated recipe paths to GOOSE_MCP_ROOT, invokes Goose without a shell, limits captured output, times out child processes, and terminates their process group during timeout or shutdown. Dependency versions are pinned in package.json and package-lock.json.

These are application-level guardrails, not a sandbox. Goose inherits the server's environment and operating-system permissions and may access resources outside the workspace through its own tools or subprocesses. Run the server under a dedicated, least-privileged OS account or container, expose only necessary credentials, and set GOOSE_MCP_ROOT explicitly for untrusted requests.

Troubleshooting

1. Subagents not working: Ensure ALPHA_FEATURES=true is set

2. Goose not found: Verify Goose CLI is installed and in PATH

3. Recipe not found: Check GOOSE_RECIPE_PATH or place recipes in working directory

License

MIT