How to connect nicemails to VS Code

Q: VS Code never asked for my key, or the server does not start.

Check the JSON: the top-level key must be servers, type must be http, and the input id in ${input:nicemails-key} must match the id in inputs. Run MCP: List Servers to see the server and its actions.

To give GitHub Copilot in VS Code an email inbox, create a nicemails API key and add nicemails to an mcp.json file as an HTTP server that sends the key in an Authorization header. VS Code asks for the key once and stores it securely; Copilot can then read, search and organize your mail and send mail you approve.

What do you need before you start?

A nicemails account with a mailbox for Copilot to use. Sign-up is free and uses a code sent to your email instead of a password.
VS Code with GitHub Copilot and its AI features turned on. Per the VS Code docs, what you can use can also depend on your organization’s policy.

This guide uses an API key. The VS Code configuration reference documents OAuth for remote servers through a client ID registered in advance. nicemails registers OAuth clients automatically and has no fixed client ID to give you, so the reliable route is the key, sent as a request header.

How do I create the API key?

In nicemails, open Settings → API keys and select Create API key.
Choose AI agent (MCP) as the key purpose.
Pick the permissions and, if you like, limit the key to one mailbox.
Copy the key. It is shown only once.

Create one key per machine or workspace. You can then revoke one without breaking the others.

How do I add nicemails to VS Code?

Run MCP: Open User Configuration from the Command Palette to use nicemails in every workspace, or create .vscode/mcp.json in a workspace folder. Add an input for the key and the nicemails server:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "nicemails-key",
      "description": "nicemails API key",
      "password": true
    }
  ],
  "servers": {
    "nicemails": {
      "type": "http",
      "url": "https://nicemails.net/mcp",
      "headers": {
        "Authorization": "Bearer ${input:nicemails-key}"
      }
    }
  }
}

Save the file. The first time the server starts, VS Code asks for the nicemails API key. Paste the key; VS Code stores it securely for later sessions.
Open Copilot Chat and ask “list my nicemails mailboxes”. Approve the tool request when it appears.
To see the server and its controls later, run MCP: List Servers.

VS Code uses servers as the top-level key, not the mcpServers key other clients use. It tries Streamable HTTP first, which nicemails supports.

Do not type the key into the MCP: Add Server form, into chat or into a shared file; the VS Code docs warn against all three. With the inputs entry, the key never appears in mcp.json, so a workspace file is safe to share.

What can Copilot do with your mailboxes?

Copilot gets the nicemails tools the key’s permissions allow. There are 8:

list_mailboxes lists the mailboxes the connection can use.
list_messages lists one folder of a mailbox, newest first.
search searches every folder of the selected mailboxes, including Spam.
get_message reads one message without marking it as read.
create_mailbox creates a new mailbox (Manage permission, account-wide connection).
move moves a message to another folder; flag marks it read, unread, starred or answered.
send_message sends from one of your mailboxes (Send permission; new recipients need your approval).

For example: “Find the latest email from the payment provider’s sandbox in the billing-test mailbox and tell me which webhook it mentions,” or “Mark every message from the CI notifier in the builds mailbox as read.”

Who approves what Copilot does?

VS Code shows tool approval requests as they come up. The VS Code docs advise approving only actions you understand.
The key decides the rest: it carries the permissions and the mailbox you chose when you created it. Read lets Copilot list, search and read; Manage adds creating mailboxes, moving messages and flags; Send adds sending.
Send approval: if a recipient is not someone you emailed from the web app, or trusted at an earlier approval, within the last 30 days, nothing is sent until you approve that message on a nicemails confirmation page while signed in. An unapproved request expires after 15 minutes.
Untrusted content: tool results mark email content as untrusted, and nothing inside an email can approve a send.
An off switch: revoke the key in nicemails under Settings → API keys. Access ends immediately.

Troubleshooting

VS Code never asked for my key, or the server does not start.

Check the JSON: the top-level key must be servers, type must be http, and the input id in ${input:nicemails-key} must match the id in inputs. Run MCP: List Servers to see the server and its actions.

The server starts but every call is unauthorized.

The key is wrong, revoked or was pasted with extra spaces. Create a new key, then change the input id in both places, for example to nicemails-key-2, so VS Code asks for the new value.

Can I sign in with OAuth instead of using a key?

The VS Code configuration reference describes OAuth through a client ID you register in advance. nicemails issues client IDs only through automatic registration, so this guide does not describe an OAuth setup for VS Code. Use a key.

Related guides

Start for free