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.

Installation

The MCP server is published to npm as butterstack-mcp. Run it with npx, no global install required:

npx -y butterstack-mcp

Source is on GitHub at ButterStack/butterstack-mcp. It reads the same credentials the butter CLI writes on login, so authenticate with the CLI first: see Authentication below and the CLI Guide.

Connecting AI Clients

Quick setup with the CLI

After butter auth login, run butter mcp install and it configures whichever of OpenCode, Claude Desktop, and Cursor it finds, using each client’s own schema. Use --opencode, --claude, or --cursor to limit it to one client, and --dry-run to preview the changes before writing. The manual snippets below remain for other clients or hand editing.

Claude Desktop

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

{
  "mcpServers": {
    "butterstack": {
      "command": "npx",
      "args": ["-y", "butterstack-mcp"]
    }
  }
}

Cursor

In Cursor, go to Settings > Features > MCP Servers and add a new server using the command: npx -y butterstack-mcp.

Antigravity

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

[mcp.servers.butterstack]
command = "npx"
args = ["-y", "butterstack-mcp"]

OpenCode

butter mcp install --opencode writes this entry for you.

Add the following to your ~/.config/opencode/opencode.jsonc (or a project-local .opencode/opencode.jsonc). OpenCode uses a different schema from Claude Desktop: type, enabled, and an array command are all required, and pasting the Claude Desktop snippet will make OpenCode fail to start.

"mcp": {
  "butterstack": {
    "type": "local",
    "command": ["npx", "-y", "butterstack-mcp"],
    "enabled": true
  }
}

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.
• changes_list: Lists a project’s changes (git commits, Perforce and Lore changelists), filterable by source, identifier, and update time. Requires read:changes.
• changes_get: Fetches one change with its files, approvals, linked builds, and tasks. Takes a change id or a commit reference (full SHA, a Perforce build’s p4-<n>, or lore-<n>), so a build’s commit_hash from builds_get resolves to its change. Requires read:changes.
• 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. A token issued before read:changes joined the CLI scope set cannot use the changes_* tools; run butter auth login again to reissue it.