# Groundmail MCP server in Zed

Connect Zed's Agent Panel to the Groundmail MCP server, and the agent can send email, check delivery, add and verify sending domains, and manage templates, webhooks and suppressions while you code. Add one entry under `context_servers` and sign in with your Groundmail account; there's no API key to paste.

**Server URL:** `https://mcp.groundmail.dev/mcp` (Streamable HTTP, OAuth) · All clients and the full tool list: [MCP server](https://docs.groundmail.dev/ai/mcp)

---

## 1. Add the server

Run **zed: open settings file** from the command palette and add Groundmail under `context_servers`:

```json
{
  "context_servers": {
    "groundmail": {
      "url": "https://mcp.groundmail.dev/mcp"
    }
  }
}
```

Or use the UI: **Settings → AI → MCP Servers → Add Server → Add Remote Server**, with the same URL.

## 2. Sign in

With no `Authorization` header in the entry, Zed starts the MCP OAuth sign-in. Your browser opens on Groundmail: sign in, choose what Zed may do (full access, or less: **Send only**, **Read only** or a custom set of [scopes](https://docs.groundmail.dev/api-keys)) and approve.

In **Settings → AI → MCP Servers**, a green dot next to **groundmail** ("Server is active") means it's connected. The connection is listed under **Settings → CLIs & agents** in Groundmail, where you can revoke it.

## 3. Use it

Open the Agent Panel and ask, for example:

- *"List my Groundmail domains and tell me which aren't verified."*
- *"Send a test email from noreply@mail.groundmail.dev to me and tell me if it was delivered."*
- *"Create a webhook for bounces pointing at https://example.com/hooks/email."*

Zed asks before each tool call unless you changed `agent.tool_permissions.default` from `"confirm"`. Keep confirmation on for tools that send email or change DNS.

If the agent reaches for other tools instead, create an agent profile that turns on the Groundmail server's tools and turns off the built-in ones you don't need.

---

## Use an API key instead

For a machine where nobody can sign in in a browser, pass a key in a header. Create one at [app.groundmail.dev/api-keys](https://app.groundmail.dev/api-keys); a [scoped key](https://docs.groundmail.dev/api-keys) limits what the agent can do.

```json
{
  "context_servers": {
    "groundmail": {
      "url": "https://mcp.groundmail.dev/mcp",
      "headers": { "Authorization": "Bearer gm_your_key_here" }
    }
  }
}
```

Zed's settings file is plain JSON on disk, so keep a key out of any project settings you commit.

## Run it locally (stdio)

```json
{
  "context_servers": {
    "groundmail": {
      "command": "npx",
      "args": ["-y", "groundmail-mcp"],
      "env": { "GROUNDMAIL_API_KEY": "gm_your_key_here" }
    }
  }
}
```

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| The dot next to the server isn't green | Hover it to see the error. Check the URL ends in `/mcp`, and that `npx` is on your `PATH` for the stdio setup. |
| No sign-in prompt appeared | Remove any `headers` from the entry: Zed only starts OAuth when there's no `Authorization` header. |
| `insufficient_scope` from a tool | The connection or key doesn't have that scope. Reconnect and grant it, or use a key with the scope. |
| Sends to other people are refused | Test sends go to your own account email. Sending to anyone else needs a verified domain: see [Test sends and idempotency](https://docs.groundmail.dev/ai/safe-defaults). |

Other editors: [GitHub Copilot (VS Code)](https://docs.groundmail.dev/ai/mcp-github-copilot) · [Warp](https://docs.groundmail.dev/ai/mcp-warp) · [Google Antigravity](https://docs.groundmail.dev/ai/mcp-antigravity) · [Cursor, Claude Code, Codex, Windsurf](https://docs.groundmail.dev/ai/mcp)