# Groundmail MCP server in GitHub Copilot (VS Code)

Connect GitHub Copilot in VS Code to the Groundmail MCP server, and Copilot's agent can send email, check delivery, add and verify sending domains, and manage templates, webhooks and suppressions from chat. It's one entry in `.vscode/mcp.json`, and you sign in with your Groundmail account, so 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)

On Copilot Business or Enterprise, an organization admin must turn on the **MCP servers in Copilot** policy before any MCP server works.

---

## 1. Add the server

Create `.vscode/mcp.json` in your project (VS Code uses a top-level `servers` key, not `mcpServers`):

```json
{
  "servers": {
    "groundmail": {
      "type": "http",
      "url": "https://mcp.groundmail.dev/mcp"
    }
  }
}
```

To make it available in every workspace instead, run **MCP: Add Server** from the Command Palette, choose **HTTP**, paste the URL and add it to your user profile. Or from a terminal:

```bash
code --add-mcp '{"name":"groundmail","type":"http","url":"https://mcp.groundmail.dev/mcp"}'
```

## 2. Start it and sign in

1. In `mcp.json`, click **Start** above the server list (or run **MCP: List Servers**, pick **groundmail** and start it).
2. VS Code asks to authenticate with `mcp.groundmail.dev`. Allow it, and your browser opens on Groundmail.
3. Sign in, choose what Copilot may do (full access, or less: **Send only**, **Read only** or a custom set of [scopes](https://docs.groundmail.dev/api-keys)) and approve.

VS Code stores the token and refreshes it. The connection is listed under **Settings → CLIs & agents** in Groundmail, where you can revoke it.

## 3. Use it

Open Copilot Chat, pick **Agent** from the mode menu, and click the tools icon to see the Groundmail tools. Then 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."*
- *"Add mail.example.com as a sending domain and show me the DNS records."*

VS Code asks you to approve tool calls before they run. Read the arguments before approving a send.

---

## Use an API key instead

For a machine where nobody can sign in in a browser, send a key in the `Authorization` header. VS Code prompts for it once and keeps it in its secret storage, so it isn't written to the file:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "groundmail-api-key",
      "description": "Groundmail API key",
      "password": true
    }
  ],
  "servers": {
    "groundmail": {
      "type": "http",
      "url": "https://mcp.groundmail.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:groundmail-api-key}"
      }
    }
  }
}
```

Create the key at [app.groundmail.dev/api-keys](https://app.groundmail.dev/api-keys). A [scoped key](https://docs.groundmail.dev/api-keys) (for example `emails:send` and `emails:read`) limits what the agent can do.

## Run it locally (stdio)

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "groundmail-api-key",
      "description": "Groundmail API key",
      "password": true
    }
  ],
  "servers": {
    "groundmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "groundmail-mcp"],
      "env": {
        "GROUNDMAIL_API_KEY": "${input:groundmail-api-key}"
      }
    }
  }
}
```

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| No Groundmail tools in chat | Switch the chat to **Agent** mode, and check the server is running under **MCP: List Servers**. |
| The server won't start on a work account | Ask an organization admin to enable the **MCP servers in Copilot** policy. |
| The browser sign-in never opened | Run **MCP: List Servers**, pick **groundmail** and restart it. Check the URL ends in `/mcp`. |
| `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: [Zed](https://docs.groundmail.dev/ai/mcp-zed) · [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)