Model Context Protocol (MCP) Guide

ButterStack supports the Model Context Protocol (MCP), allowing you to connect AI agents (like Claude Desktop, Cursor, and Antigravity) directly to your game development pipeline.

Connecting AI Clients

Claude Desktop

To connect Claude Desktop to your ButterStack MCP server, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "butterstack": {
      "command": "butter",
      "args": ["mcp", "start"]
    }
  }
}

Cursor

In Cursor, go to Settings > Features > MCP Servers and add a new server using the command: butter mcp start.

Antigravity

For Antigravity, add the MCP server configuration in your antigravity.toml:

[mcp.servers.butterstack]
command = "butter"
args = ["mcp", "start"]

Available Tools

The ButterStack MCP server exposes the following tools to AI agents (butterstack-mcp/index.js):

• projects_list: Lists projects the authenticated user belongs to.
• projects_get: Fetches details of a specific project.
• tasks_list: Retrieves tasks for a project.
• tasks_create: Creates a new task.
• tasks_update: Modifies a task (e.g., changing its state or assignee).
• builds_list: Lists build runs for a project.
• builds_get: Fetches details of a specific build run.
• builds_investigate_failure: Triggers an AI failure investigation on a failed build run. Spends account credits and requires write:builds on the underlying token.
• assets_list_pending: Lists assets with a pending approval decision.
• assets_get_details: Fetches details of a specific asset.
• assets_approve: Approves a pending asset.
• assets_deny: Denies a pending asset with feedback.

Resources

• butterstack://projects: Live list of all game projects accessible with the current credentials.

Prompt Templates

The ButterStack MCP server includes pre-defined prompts to help initialize AI contexts:

• triage_broken_build: Walks the AI through diagnosing a failed build for a project.
• batch_asset_review: Walks the AI through reviewing and deciding on a project’s pending asset queue.

Example usage in Claude:

“Use the ButterStack triage_broken_build prompt for project MyGame.”

Authentication

The MCP server reads the credentials butter auth login writes to ~/.config/butterstack/credentials.json (or BUTTERSTACK_API_TOKEN in the environment). Run butter auth login once before starting the server; see the CLI Guide for scoping the token to only what your tools need.