Connecting an MCP Email Server to Claude Desktop: A Step-by-Step Guide

Claude Desktop already runs whatever MCP servers you point it at: a filesystem server for local files, a shell server for commands, a database server for queries against production data. Email works the same way. Instead of drafting a reply yourself and pasting it into Gmail, Claude drafts it and sends it, then reads whatever comes back, all inside the same conversation. This post walks through wiring up @ujexdev/postbox-mcp, the MCP server Ujex ships for its Postbox email subsystem, so a Claude Desktop conversation can read and send mail through your agent's own inbox by the end of it.

What you're actually connecting

Postbox is the part of Ujex that gives an agent a real inbox: sending, receiving, and threaded conversations, backed by an actual mail server rather than a webhook simulation bolted onto a shared address. Inbound mail is verified with signed webhooks, so a message that lands in your agent's inbox is provably from Ujex's mail infrastructure and not something spoofed further up the chain.

@ujexdev/postbox-mcp is the piece that makes Postbox usable from an MCP client. It's a small server process that speaks MCP on one side and calls the Postbox API on the other, translating "send an email" or "check for new messages" into whatever calls Postbox actually expects underneath. Because MCP is a protocol and not a Claude-specific feature, the same server works with any MCP-compatible client. Claude Desktop is just the one this post walks through, since it's the most common place people first hook an agent up to a real inbox.

Two kinds of Ujex keys, and which one to use here

Ujex separates two identities that are easy to conflate at first. Your human account signs in through Firebase Auth, same as any SaaS login. Your agent, separately, gets its own identity through API keys: a device key (prefix ap_live_) that authenticates broadly as the agent, or an inbox-scoped key (prefix apk_sc_) that's locked to a single Postbox inbox and nothing else.

For an MCP server sitting in a plaintext config file on your laptop, I'd default to the inbox-scoped key every time. It's not that the device key would fail here, it's that handing a local process broad agent-account access to do one job, email, is more blast radius than the job needs.

Wire it up

Four steps get you from nothing to a working setup: get a key, edit the config, restart, and confirm it worked with a real message.

Copy{
  "mcpServers": {
    "ujex-postbox": {
      "command": "npx",
      "args": ["-y", "@ujexdev/postbox-mcp"],
      "env": { "UJEX_API_KEY": "YOUR_UJEX_API_KEY" }
    }
  }
}

Confirm the tools actually loaded

Before trusting Claude with a real send, it's worth checking that the server registered at all. Claude Desktop surfaces connected MCP servers and their tools in its settings, or via a small tools icon near the chat input depending on your version. Look for an entry tied to whatever key you used in the config, ujex-postbox in the snippet above, with a handful of tools listed underneath it: something along the lines of sending a message, listing recent messages, and reading a thread. Exact tool names are defined by the server itself and can change between releases, so treat what's actually in the UI as the source of truth over anything printed here, and check docs.ujex.dev if you want to know the current list ahead of time. If the entry isn't there at all, skip down to the troubleshooting section before trying to send anything.

Send a real test email

Once the tools show up, ask Claude to send a short test message from the agent's inbox to an address you can actually check, your own personal email works fine for this. It should land within a minute or two, with the agent's Postbox address as the sender. Reply to it from your inbox. Then ask Claude to check the inbox again: a correctly wired setup pulls your reply back in as part of the same thread rather than a disconnected new message, because Postbox tracks threaded conversations instead of treating every message as standalone.

That round trip, agent sends, human replies, agent reads the reply back in context, is the real proof the wiring is correct. It matters more than the tools simply appearing in a list, since a stale key or a misconfigured inbox can still show tools in the UI while every actual call fails.

When something doesn't work

Two things account for almost every "the tools didn't show up" report. First, a JSON syntax error in the config file: a missing comma between server entries, a trailing comma after the last key, an unmatched brace. Claude Desktop tends to fail quietly rather than telling you the config didn't parse, so run the file through a JSON validator, or just read it slowly, before assuming the server itself is broken.

Second, and more common than it should be: Claude Desktop wasn't actually restarted. Closing the window is not the same as quitting the app, most desktop apps on macOS and Windows keep running after the last window closes, and Claude Desktop is no exception. Quit it from the menu bar or system tray, confirm there's no lingering Claude Desktop process, and relaunch clean.

If both of those check out and the server still isn't listed, the next suspect is the key itself, expired, revoked, or scoped to an inbox that no longer exists will make the server fail to authenticate on startup even though the config file is syntactically perfect. Generate a fresh inbox-scoped key from the dashboard and swap it in if you're not sure.