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

Example: Java LSP via LSP4J-MCP​

You can add Java IDE navigation tools to GenieBuilder by running the open source stephanj/LSP4J-MCP server over stdio. That project wraps Eclipse JDTLS with MCP so chat and CLI agents can resolve Java symbols, jump to definitions, and find references inside a Java workspace.

Upstream prerequisites:

  • Java 21+
  • Maven 3.8+
  • JDTLS installed locally, for example brew install jdtls

Build the server from the upstream repository:

git clone https://github.com/stephanj/LSP4J-MCP.git
cd LSP4J-MCP
mvn clean package

This produces a shaded jar at target/lsp4j-mcp-1.0.0-SNAPSHOT.jar.

In GenieBuilder, open Settings → MCP Servers and add a stdio server with:

  • Name: Java LSP
  • Transport: stdio
  • Command: java
  • Arguments: -jar /Users/stephan/IdeaProjects/LSP4J-MCP/target/lsp4j-mcp-1.0.0-SNAPSHOT.jar /Users/stephan/IdeaProjects/callforpapers jdtls

If you prefer the JSON editor, use:

{
  "name": "Java LSP",
  "transport": "stdio",
  "command": "java",
  "args": [
    "-jar",
    "/Users/stephan/IdeaProjects/LSP4J-MCP/target/lsp4j-mcp-1.0.0-SNAPSHOT.jar",
    "/Users/stephan/IdeaProjects/callforpapers",
    "jdtls"
  ]
}

The two path arguments are:

  • The path to the built LSP4J-MCP jar
  • The root of the Java project you want JDTLS to index

The final jdtls argument is the command used to launch the Eclipse JDT Language Server. Adjust it if JDTLS is installed under a different executable name or location on your machine.

According to the upstream project, this server exposes Java-focused MCP tools such as:

  • find_symbols
  • find_references
  • find_definition
  • document_symbols
  • find_interfaces_with_method

Once enabled, you can ask GenieBuilder prompts like:

  • "Find all classes named Repository in this project."
  • "Go to the definition of the symbol under src/main/java/...."
  • "Find every reference to processOrder."

For more details, examples, and updates to the server itself, see the upstream project: https://github.com/stephanj/LSP4J-MCP.

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
Last updated on