MCP Directory

How to add Heroku MCP Server to Windsurf

Manage Heroku apps, dynos, add-ons, pipelines, and Postgres from your AI agent via the official Heroku CLI. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 78★ · stdio · apikey · official

Windsurf config for Heroku MCP Server

npx -y @heroku/mcp-server
{
  "mcpServers": {
    "heroku-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@heroku/mcp-server"
      ],
      "env": {
        "HEROKU_API_KEY": "<your-heroku-auth-token>"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Heroku MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Heroku MCP Server's tools become available to Cascade.

Before you start

  • Heroku CLI v10.8.1 or higher installed globally (required for heroku mcp:start; verify with heroku --version)
  • A Heroku account; for the npx mode, an auth token from heroku authorizations:create set as HEROKU_API_KEY
  • Node.js with npx for the @heroku/mcp-server launch mode

What Heroku MCP Server can do in Windsurf

list_apps

List Heroku apps, filterable by personal, collaborator, team, or space.

get_app_info

Detailed app info including configuration, dynos, and add-ons.

create_app

Create an app with region, team, and space settings.

rename_app

Rename an existing app.

transfer_app

Transfer app ownership to another user or team.

deploy_to_heroku

Deploy projects with app.json configuration, supporting teams, private spaces, and environment setup.

deploy_one_off_dyno

Run code or commands in a sandboxed one-off dyno with file creation, network access, env vars, and auto cleanup.

ps_list

List all dynos for an app.

Security

Tools can create, scale, transfer, and deploy real apps and run SQL against production Postgres — an agent mistake costs money or data, so review tool calls before approving. Prefer heroku mcp:start (no token in config); if you use HEROKU_API_KEY, scope it via heroku authorizations:create rather than pasting your account's long-lived token.

Heroku MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Heroku MCP Server config there under the "mcpServers" key and restart the client.

Is Heroku MCP Server safe to use with Windsurf?

Tools can create, scale, transfer, and deploy real apps and run SQL against production Postgres — an agent mistake costs money or data, so review tool calls before approving. Prefer heroku mcp:start (no token in config); if you use HEROKU_API_KEY, scope it via heroku authorizations:create rather than pasting your account's long-lived token.

Is the Heroku MCP server safe to connect to production?

It executes with the full privileges of your CLI session or auth token — including app deletion-adjacent operations like transfers, scaling, and live SQL via pg_psql. Use heroku mcp:start to avoid storing tokens, keep human approval on write operations, and consider a dedicated authorization token you can revoke.

Do I need the Heroku CLI even when using npx?

Yes. The server is built around the Heroku CLI and requires v10.8.1+ installed globally. The npx package handles the MCP wiring, while heroku mcp:start additionally reuses your CLI authentication.

How do I get a HEROKU_API_KEY?

Run heroku authorizations:create (or heroku auth:token for the current session token), or create an authorization under Account Settings → Applications in the dashboard. Put the value in the env block of your MCP config.

View repo Full Heroku MCP Server page