Skip to main content

MCP Integration

Model Context Protocol (MCP) is the backbone of GenieBuilder's extensibility. It provides a standardized way to expose tools to AI models, enabling them to interact with files, git, tasks, and more.

MCP Settings

What is MCP?​

MCP is a protocol that allows AI applications to:

  • Discover tools — Dynamically learn what capabilities are available
  • Invoke tools — Execute operations through standardized interfaces
  • Receive results — Get structured responses from tool execution

Think of it as a USB-C for AI tools — a common interface that any AI model can use to interact with external systems.

Default MCP Servers​

Backlog Sidecar​

The primary MCP server for task management:

Tools provided:

  • task_list — List all tasks
  • task_view — Get task details
  • task_create — Create new task
  • task_edit — Update task fields
  • task_archive — Archive completed tasks
  • milestone_list — List milestones

Configuration:

  • Command: backlog mcp start
  • Transport: stdio (JSON-RPC)
  • Auto-restart: Yes

GenieBuilder MCP Tools​

Built-in MCP tools for enhanced development workflows:

Tools provided:

  • File System: Read, write, and manage workspace files
  • Shell: Execute shell commands with approval
  • Git: Branch, commit, diff, and status operations
  • Backlog: Task management integration

Features:

  • All tools require explicit approval for mutating operations
  • Read-only operations are auto-approved for smooth workflows
  • Extensible through custom MCP servers

Adding Custom MCP Servers​

You can extend GenieBuilder with custom MCP servers:

Configuration​

In Settings → MCP Servers, add:

Name: My Custom Server
Transport: stdio  # or http
Command: my-mcp-server
Arguments: ["--port", "8080"]
Environment:
  API_KEY: "secret"

HTTP Transport​

For remote MCP servers:

Name: Remote MCP
Transport: http
URL: http://localhost:3000/mcp
Headers:
  Authorization: Bearer token

Tool Discovery​

Custom tools automatically appear in:

  • Chat tool list
  • Workflow step configuration
  • Approval dialogs

Tool Schema​

MCP tools follow a standardized schema:

{
  "name": "git.commit",
  "description": "Commit changes to git",
  "parameters": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "Commit message"
      }
    },
    "required": ["message"]
  }
}

GenieBuilder sanitizes and validates tool schemas for safety.

Security Model​

Approval Gates​

Mutating tools require explicit approval:

Auto-approved (read-only):

  • task_view
  • git.status
  • file.read

Requires approval (mutating):

  • task_edit
  • git.commit
  • file.write
  • shell.execute

Approval Dialog​

When a mutating tool is called:

  1. Execution pauses
  2. Dialog shows tool name and parameters
  3. User reviews and approves/denies
  4. Execution continues or aborts

Schema Validation​

Tool parameters are validated before execution:

  • Type checking
  • Required field validation
  • Enum value verification
  • String length limits

Tool Execution Flow​

1. AI model requests tool execution
        ↓
2. Main process receives request
        ↓
3. Schema validation
        ↓
4. Is mutating? ──Yes──► Show approval dialog
        ↓ No                    ↓
5. Route to MCP server    User approves?
        ↓                       ↓
6. Execute tool      No ──► Abort
        ↓ Yes
7. Return result to AI

Health Monitoring​

The MCP Hub monitors sidecar health:

Checks​

  • Process status — Is the sidecar running?
  • JSON-RPC — Responding to pings?
  • Tool list — Can refresh tool registry?

Recovery​

On failure detection:

  1. Log the failure
  2. Attempt graceful shutdown
  3. Restart sidecar
  4. Re-initialize connection
  5. Refresh tool list
  6. Notify renderer

MCP for CLI Runners​

CLI Runners receive MCP configuration automatically:

  1. GenieBuilder generates temp MCP config JSON
  2. Config includes all enabled servers
  3. Passed to CLI via --mcp-config flag
  4. CLI runner can use same tools as chat

This enables powerful patterns like:

  • Claude Code with Backlog task tools
  • Kimi CLI with git integration
  • Codex with shell access

Future Enhancements​

Planned MCP improvements:

  • Resource support — Binary data handling
  • Prompts — Pre-defined prompt templates
  • Sampling — AI-powered tool selection
  • Multi-server workflows — Cross-server operations