{ "markdown": "

\n \"Heroku\"\n

\n\n# Heroku Code MCP\n\n> A compact MCP server for the Heroku Platform API using a Code Mode pattern: `search` + `execute` + `auth_status`.\n\n\n\nHeroku Code MCP gives agent clients a small, token-efficient control surface for Heroku operations. Pair it with [Heroku Skills](https://github.com/dsouzaAnush/heroku-skills) when you want workflow guidance, safety checks, and Heroku product context alongside live API tools.\n\nDesign references:\n- [Cloudflare Code Mode MCP](https://blog.cloudflare.com/code-mode-mcp/)\n- [Anthropic: Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)\n\n## Quick Start\n\nDefault MCP URL: `http://127.0.0.1:3000/mcp`\n\n```bash\ngit clone https://github.com/dsouzaAnush/heroku-code-mcp.git\ncd heroku-code-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nSeed auth from the Heroku CLI:\n\n```bash\nheroku auth:whoami\nnpm run seed:token\n```\n\nStart the server:\n\n```bash\nTOKEN_STORE_PATH=./data/tokens.integration.json \\\nTOKEN_ENCRYPTION_KEY_BASE64=\"\" \\\nPORT=3000 HOST=127.0.0.1 npm run dev\n```\n\nSmoke test:\n\n```bash\ncurl -sS http://127.0.0.1:3000/healthz\nMCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp\n```\n\nBefore npm publication, the package can also run from GitHub:\n\n```bash\nHOST=127.0.0.1 PORT=3333 \\\nTOKEN_STORE_PATH=\"$HOME/.heroku-code-mcp/tokens.json\" \\\nTOKEN_ENCRYPTION_KEY_BASE64=\"\" \\\nWRITE_CONFIRMATION_SECRET=\"\" \\\nnpx -y github:dsouzaAnush/heroku-code-mcp\n```\n\n## Install in Agent Clients\n\n### \"Claude Claude Code\n\nInstall the companion plugin for skills plus MCP wiring:\n\n```bash\nclaude plugin marketplace add dsouzaAnush/heroku-plugin\nclaude plugin install heroku@heroku-plugin\nclaude plugin enable heroku@heroku-plugin\n```\n\nOr add the running MCP server directly:\n\n```bash\nclaude mcp add \\\n --transport http \\\n --scope local \\\n heroku-code-mcp \\\n http://127.0.0.1:3000/mcp \\\n --header \"x-user-id: default\"\n```\n\n### \"Claude Claude Desktop\n\nUse the HTTP endpoint directly when supported:\n\n```json\n{\n \"mcpServers\": {\n \"heroku-code-mcp\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:3000/mcp\",\n \"headers\": {\n \"x-user-id\": \"default\"\n }\n }\n }\n}\n```\n\nFor Desktop builds that expect stdio servers, bridge through `mcp-remote`:\n\n```json\n{\n \"mcpServers\": {\n \"heroku-code-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"http://127.0.0.1:3000/mcp\", \"--allow-http\", \"--header\", \"x-user-id:default\"]\n }\n }\n}\n```\n\nBuild a `.mcpb` bundle with:\n\n```bash\nnpm run build:mcpb\n```\n\n### \"OpenAI Codex\n\nCodex uses [Heroku Plugin](https://github.com/dsouzaAnush/heroku-plugin) for skills and optional MCP wiring:\n\n```bash\ncodex plugin marketplace add dsouzaAnush/heroku-plugin --ref main\n```\n\nEnable `heroku-plugin@heroku-plugin` in the Codex Plugins tab, or add:\n\n```toml\n[plugins.\"heroku-plugin@heroku-plugin\"]\nenabled = true\n```\n\nRun this MCP server on `http://127.0.0.1:3333/mcp` when you want live Heroku API tools through the plugin.\n\n### \"Cursor\" Cursor\n\n```bash\ngit clone https://github.com/dsouzaAnush/heroku-plugin.git\ncursor agent --plugin-dir heroku-plugin\n```\n\nAdd the MCP server to `~/.cursor/mcp.json` or project-local `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"heroku-code-mcp\": {\n \"type\": \"streamable-http\",\n \"url\": \"http://127.0.0.1:3333/mcp\",\n \"headers\": {\n \"x-user-id\": \"default\"\n }\n }\n }\n}\n```\n\n### Other MCP Clients\n\nUse streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"heroku-code-mcp\": {\n \"transport\": \"streamable_http\",\n \"url\": \"http://127.0.0.1:3000/mcp\",\n \"headers\": {\n \"x-user-id\": \"default\"\n }\n }\n }\n}\n```\n\nOr bridge to stdio:\n\n```json\n{\n \"mcpServers\": {\n \"heroku-code-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"http://127.0.0.1:3000/mcp\", \"--allow-http\", \"--header\", \"x-user-id:default\"]\n }\n }\n}\n```\n\n## How It Works\n\n| Tool | What it does | Why it exists |\n| --- | --- | --- |\n| `auth_status` | Reports whether the caller is authenticated with Heroku | Lets agents branch cleanly before API work |\n| `search` | Ranks Heroku operations from schema and docs context | Avoids exposing dozens of endpoint-shaped tools up front |\n| `execute` | Validates params/body and calls the selected Heroku operation | Gives one deterministic execution path |\n\nTypical flow:\n\n1. Call `auth_status`.\n2. Call `search` with natural language intent.\n3. Choose one `operation_id`.\n4. Call `execute` with `path_params`, `query_params`, and `body`.\n5. For writes, run `dry_run=true`, then replay with `confirm_write_token` and `ALLOW_WRITES=true`.\n\nExamples:\n\n```json\n{\n \"query\": \"list apps\",\n \"limit\": 5\n}\n```\n\n```json\n{\n \"operation_id\": \"GET /apps\"\n}\n```\n\n```json\n{\n \"operation_id\": \"PATCH /apps/{app_identity}\",\n \"path_params\": {\n \"app_identity\": \"my-app\"\n },\n \"body\": {\n \"maintenance\": true\n },\n \"dry_run\": true\n}\n```\n\n## Safety and Configuration\n\nMutations (`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.\n\nKey env vars:\n- `ALLOW_WRITES`\n- `REQUEST_TIMEOUT_MS`\n- `MAX_RETRIES`\n- `CATALOG_CACHE_PATH`\n- `READ_CACHE_TTL_MS`\n- `EXECUTE_MAX_BODY_BYTES`\n- `EXECUTE_BODY_PREVIEW_CHARS`\n\nFull example: `.env.example`\n\n## Benchmarks\n\nBenchmarks were captured on February 22, 2026 on the same machine and account for both implementations.\n\n| Metric | `heroku-code-mcp` | official Heroku MCP | Delta |\n| --- | ---: | ---: | ---: |\n| Tool count | 3 | 37 | 91.9% lower |\n| Tool-list payload bytes | 1,469 | 25,500 | 94.2% lower |\n| Tool-list approx tokens | 368 | 6,375 | 94.2% lower |\n| Connect avg | 14.8 ms | 10,168.7 ms | 687x faster |\n| `list_tools` avg | 4.3 ms | 10.3 ms | 2.4x faster |\n| Read op avg | 528.0 ms (`execute GET /apps`) | 9,697.4 ms (`list_apps`) | 18.4x faster |\n\nCharts:\n- ![Context reduction chart](benchmarks/graphs/context-reduction.svg)\n- ![Latency comparison chart](benchmarks/graphs/latency-comparison.svg)\n\nFull methodology and artifacts live in [`BENCHMARKS.md`](BENCHMARKS.md) and `benchmarks/results/`.\n\n## Development and Release\n\nValidate locally:\n\n```bash\nnpm run build\nnpm test\nnpm run validate:server\nnpm run publish:dry-run\n```\n\nThis repo uses free GitHub Actions:\n- `validate.yml` runs build, tests, `server.json` validation, and npm pack dry-run on PRs and pushes to `main`.\n- `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.\n- Dependabot checks npm and GitHub Actions dependencies weekly.\n\nPublish manually when needed:\n\n```bash\nnpm publish --access public\nmcp-publisher login github\nmcp-publisher publish server.json\n```\n\nFor 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`.\n\n## Repository Layout\n\n- `src/schema/*`: ingestion, operation normalization, and cache\n- `src/search/*`: search index and ranking\n- `src/execute/*`: validation and Heroku API execution\n- `src/auth/*`: OAuth and encrypted token storage\n- `tests/*`: catalog, search, and execute tests\n- `benchmarks/results/*`: benchmark artifacts\n- `server.json`: MCP Registry metadata\n\n## Brand and Troubleshooting\n\nThis repo includes the official Heroku wordmark and mark under [`assets`](assets). Use them according to the [Heroku Brand Guidelines](https://devcenter.heroku.com/articles/heroku-brand-guidelines).\n\nCommon fixes:\n- MCP Inspector connection error: confirm URL `http://127.0.0.1:3000/mcp` and server health.\n- `AUTH_REQUIRED`: seed a token or complete OAuth.\n- Write blocked: confirm `ALLOW_WRITES=true` and send the dry-run confirmation token.\n- Large response body: narrow query scope or lower output caps.\n", "bytes": 8418, "sha": "c1e623f00481f1c74bf6ff271feb7993f9e1047bfd3c11fcbaace999b4e1dcf9", "repo_slug": "dsouzaanush/heroku-code-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_dsouzaanush_heroku_code_mcp_dc5b13df/readme" }