Connect Windsurf to Postal

Check these points before opening Windsurf's settings. They prevent most connection failures.

• A team with the "MCP server" plan feature (mcp_access); without it the server responds 403 plan_limit_reached.
• To send emails, the team needs at least one verified domain.
• If you will use an API key: create the key in the dashboard, under API keys. It starts with ps_; a send-only key is enough if you will only send.
• Each connection acts on a single team. To use another team, connect again and pick the other one.
• Connections are listed under Settings › AI connections in the dashboard, where they can be revoked at any time.

Follow the steps in order. The server address is always https://api.postal.so/mcp. Recommended path: API key (signing in with your account, via OAuth, also works).

1. 1

   Open the mcp_config.json file from Cascade's MCP panel (the current documentation points to ~/.config/devin/mcp_config.json on macOS/Linux and %APPDATA%\devin\mcp_config.json on Windows; older installations use ~/.codeium/windsurf/mcp_config.json).

2. 2

   Add the block below. In Windsurf, the remote URL field is serverUrl.

3. 3

   For an API key, use the second block and set POSTAL_API_KEY in the environment (the ${env:NAME} syntax is replaced with the variable's value).

4. 4

   Refresh the server list in the MCP panel. With OAuth, the Postal sign-in opens on first use: choose the team and click Allow.

{
  "mcpServers": {
    "postal": {
      "serverUrl": "https://api.postal.so/mcp"
    }
  }
}

{
  "mcpServers": {
    "postal": {
      "serverUrl": "https://api.postal.so/mcp",
      "headers": {
        "Authorization": "Bearer ${env:POSTAL_API_KEY}"
      }
    }
  }
}

Postal splits access into three levels, explained in the scopes table. For Windsurf:

The simplest proof is to ask for something read-only inside Windsurf itself. The connection also appears under Settings › AI connections, in the Postal dashboard, with the app, the team and the last use.

For those who want the technical proof

npx @modelcontextprotocol/inspector --cli https://api.postal.so/mcp \
  --transport http \
  --header "Authorization: Bearer ps_..." \
  --method tools/list

The Inspector proves that the Postal server responds. It does not test Windsurf itself. The full walkthrough is in Validate the connection.

Go through the list in order. Then read what we know (and what we don't) about Windsurf.

What was tested and what was not