Heroku Code MCP

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.git

cd heroku-code-mcp npm install npm run build npm test

Seed auth from the Heroku CLI:

heroku auth:whoami

npm run seed:token

Start the server:

TOKEN_STORE_PATH=./data/tokens.integration.json \

TOKEN_ENCRYPTION_KEY_BASE64=" " \ PORT=3000 HOST=127.0.0.1 npm run dev

Smoke test:

curl -sS http://127.0.0.1:3000/healthz

MCP_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=" " \ WRITE_CONFIRMATION_SECRET=" " \ npx -y github:dsouzaAnush/heroku-code-mcp

Install in Agent Clients

Claude Code

Install the companion plugin for skills plus MCP wiring:

claude plugin marketplace add dsouzaAnush/heroku-plugin

claude plugin install heroku@heroku-plugin claude 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

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

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

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

cursor 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: - -

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

Development and Release

Validate locally:

npm run build

npm test npm run validate:server npm 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 public

mcp-publisher login github mcp-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.