Heroku Code MCP

[Heroku]

Heroku Code MCP

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

Heroku Code MCP gives agent clients a small, token-efficient control surface for Heroku operations. Pair it with Heroku Skills when you want workflow guidance, safety checks, and Heroku product context alongside live API tools.

Design references:

• Cloudflare Code Mode MCP
• Anthropic: Building Effective Agents

Quick Start

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

git clone https://github.com/dsouzaAnush/heroku-code-mcp.gitcd heroku-code-mcpnpm installnpm run buildnpm test

Seed auth from the Heroku CLI:

heroku auth:whoaminpm run seed:token

Start the server:

TOKEN_STORE_PATH=./data/tokens.integration.json \TOKEN_ENCRYPTION_KEY_BASE64="<seed-output-key>" \PORT=3000 HOST=127.0.0.1 npm run dev

Smoke test:

curl -sS http://127.0.0.1:3000/healthzMCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

Before npm publication, the package can also run from GitHub:

HOST=127.0.0.1 PORT=3333 \TOKEN_STORE_PATH="$HOME/.heroku-code-mcp/tokens.json" \TOKEN_ENCRYPTION_KEY_BASE64="<base64-32-byte-key>" \WRITE_CONFIRMATION_SECRET="<random-secret>" \npx -y github:dsouzaAnush/heroku-code-mcp

Install in Agent Clients

[Claude Code] Claude Code

Install the companion plugin for skills plus MCP wiring:

claude plugin marketplace add dsouzaAnush/heroku-pluginclaude plugin install heroku@heroku-pluginclaude plugin enable heroku@heroku-plugin

Or add the running MCP server directly:

claude mcp add \  --transport http \  --scope local \  heroku-code-mcp \  http://127.0.0.1:3000/mcp \  --header "x-user-id: default"

[Claude Desktop] Claude Desktop

Use the HTTP endpoint directly when supported:

{  "mcpServers": {    "heroku-code-mcp": {      "type": "http",      "url": "http://127.0.0.1:3000/mcp",      "headers": {        "x-user-id": "default"      }    }  }}

For Desktop builds that expect stdio servers, bridge through mcp-remote:

{  "mcpServers": {    "heroku-code-mcp": {      "command": "npx",      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--allow-http", "--header", "x-user-id:default"]    }  }}

Build a .mcpb bundle with:

npm run build:mcpb

[OpenAI Codex] Codex

Codex uses Heroku Plugin for skills and optional MCP wiring:

codex plugin marketplace add dsouzaAnush/heroku-plugin --ref main

Enable heroku-plugin@heroku-plugin in the Codex Plugins tab, or add:

[plugins."heroku-plugin@heroku-plugin"]enabled = true

Run this MCP server on http://127.0.0.1:3333/mcp when you want live Heroku API tools through the plugin.

[Cursor] Cursor

git clone https://github.com/dsouzaAnush/heroku-plugin.gitcursor agent --plugin-dir heroku-plugin

Add the MCP server to ~/.cursor/mcp.json or project-local .cursor/mcp.json:

{  "mcpServers": {    "heroku-code-mcp": {      "type": "streamable-http",      "url": "http://127.0.0.1:3333/mcp",      "headers": {        "x-user-id": "default"      }    }  }}

Other MCP Clients

Use streamable HTTP:

{  "mcpServers": {    "heroku-code-mcp": {      "transport": "streamable_http",      "url": "http://127.0.0.1:3000/mcp",      "headers": {        "x-user-id": "default"      }    }  }}

Or bridge to stdio:

{  "mcpServers": {    "heroku-code-mcp": {      "command": "npx",      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--allow-http", "--header", "x-user-id:default"]    }  }}

How It Works

Typical flow:

1. Call auth_status.
2. Call search with natural language intent.
3. Choose one operation_id.
4. Call execute with path_params, query_params, and body.
5. For writes, run dry_run=true, then replay with confirm_write_token and ALLOW_WRITES=true.

Examples:

{  "query": "list apps",  "limit": 5}

{  "operation_id": "GET /apps"}

{  "operation_id": "PATCH /apps/{app_identity}",  "path_params": {    "app_identity": "my-app"  },  "body": {    "maintenance": true  },  "dry_run": true}

Safety and Configuration

Mutations (POST, PATCH, PUT, DELETE) are blocked by default. To allow a write, set ALLOW_WRITES=true, request a dry run, and replay with the returned confirm_write_token. Sensitive headers and body fields are redacted.

Key env vars:

• ALLOW_WRITES
• REQUEST_TIMEOUT_MS
• MAX_RETRIES
• CATALOG_CACHE_PATH
• READ_CACHE_TTL_MS
• EXECUTE_MAX_BODY_BYTES
• EXECUTE_BODY_PREVIEW_CHARS

Full example: .env.example

Benchmarks

Benchmarks were captured on February 22, 2026 on the same machine and account for both implementations.

Charts:

• [Context reduction chart]
• [Latency comparison chart]

Full methodology and artifacts live in BENCHMARKS.md and benchmarks/results/.

Development and Release

Validate locally:

npm run buildnpm testnpm run validate:servernpm run publish:dry-run

This repo uses free GitHub Actions:

• validate.yml runs build, tests, server.json validation, and npm pack dry-run on PRs and pushes to main.
• release.yml runs on v* tags, builds the .mcpb, updates release server.json, creates or updates the GitHub Release, and publishes to the MCP Registry through GitHub OIDC.
• Dependabot checks npm and GitHub Actions dependencies weekly.

Publish manually when needed:

npm publish --access publicmcp-publisher login githubmcp-publisher publish server.json

For CI-based npm publishing, configure npm trusted publishing for repo dsouzaAnush/heroku-code-mcp and workflow release.yml, then run the release workflow with publish_npm=true.

Repository Layout

• src/schema/*: ingestion, operation normalization, and cache
• src/search/*: search index and ranking
• src/execute/*: validation and Heroku API execution
• src/auth/*: OAuth and encrypted token storage
• tests/*: catalog, search, and execute tests
• benchmarks/results/*: benchmark artifacts
• server.json: MCP Registry metadata

Brand and Troubleshooting

This repo includes the official Heroku wordmark and mark under assets. Use them according to the Heroku Brand Guidelines.

Common fixes:

• MCP Inspector connection error: confirm URL http://127.0.0.1:3000/mcp and server health.
• AUTH_REQUIRED: seed a token or complete OAuth.
• Write blocked: confirm ALLOW_WRITES=true and send the dry-run confirmation token.
• Large response body: narrow query scope or lower output caps.