Heroku Code MCP Server

Heroku Code MCP

A token-efficient MCP server for the Heroku Platform API using a Code Mode pattern: search + execute + auth_status.

Design references:

• Cloudflare Code Mode MCP
• Anthropic: Building Effective Agents (advanced tool use)

Context Comparison

The practical impact is that the agent starts with a much smaller tool schema, then asks the server for just-in-time endpoint discovery. This keeps prompt budget available for user intent, planning, and response quality instead of spending it on static endpoint metadata.

The Problem

Heroku’s API surface is broad, and an endpoint-per-tool MCP model makes the agent choose between many tools before it has enough task context. That usually increases tool-selection ambiguity, consumes tokens early, and makes multi-step tasks more brittle. The issue is not that many tools are inherently bad, but that model context is scarce and endpoint selection is an agent planning problem, not just a transport problem.

The Approach

This server applies a Code Mode-style control loop with deterministic inputs:

1. search maps natural language intent to ranked operation_id candidates.
2. execute validates and performs the selected Heroku API operation.
3. auth_status provides explicit auth state so agents can branch cleanly.

The server holds schema intelligence and safety policy centrally. The agent gets a small control surface and a stable execution contract.

Tools

Agent                           MCP Server
  │                                  │
  ├──search({query: "list apps"})──►│ rank operations from catalog/index
  │◄──[GET /apps, ...]───────────────│
  │                                  │
  ├──execute({operation_id: ...})───►│ validate + call Heroku API
  │◄──{status, headers, body}────────│

Benchmark Highlights

Benchmarks were captured on February 22, 2026 on the same machine and account for both implementations. The numbers below compare this repo’s local HTTP MCP endpoint against the official Heroku MCP server over stdio.

Raw Comparison

Comparison Graphs

These are static charts so labels stay readable in GitHub without giant auto-scaled Mermaid panels.

How to Read These Results

The strongest win is context footprint. A 3-tool interface materially lowers initial prompt overhead and reduces tool-choice branching for the model. The second win is connection and read-path latency under this benchmark harness. In measured runs, the official Heroku MCP paid a much larger connect-time cost, and its measured read operation was substantially slower than execute GET /apps on this server.

This does not mean every endpoint in every environment will always have the same multiplier. It means the measured default experience in this setup favored the Code Mode control surface for both context economy and latency.

Benchmark Methodology

• Date: February 22, 2026.
• Environment: same local machine, same Heroku account, warm network.
• Custom server run count: 10.
• Official server run count: 3.
• Context estimate: ceil(list_tools_json_bytes / 4) for rough token approximation.
• Read comparison pairing:
  • Custom: execute GET /apps
  • Official: list_apps

Artifacts:

• benchmarks/results/context-footprint-2026-02-22.json
• benchmarks/results/custom-local-http-2026-02-22.json
• benchmarks/results/official-heroku-mcp-start-2026-02-22.json
• BENCHMARKS.md

Get Started

MCP URL: http://127.0.0.1:3000/mcp

cd heroku
npm install
npm run build
npm