@ujexdev/postbox-mcp

Model Context Protocol server that exposes Ujex Inbox to any MCP client — Claude Desktop, Cursor, Cline, Zed, Continue, etc. Drop the JSON snippet below into your client config and your agent gets a full, zod-validated email toolkit without writing a line of glue code.

Ujex Inbox is Ujex's outbound/inbound email service: DKIM/SPF/DMARC-aware, with per-message prompt-injection risk signals and require_human approval gates. This MCP server is the Inbox edge of the wider Ujex core loop: Inbox email, human Approvals, Evidence, and Provenance. It is a thin stdio-based bridge — no data is stored locally.

Install

npm i -g @ujexdev/postbox-mcp

or run it on demand with npx (no global install needed — most MCP clients do this automatically):

npx -y @ujexdev/postbox-mcp

Configuration

All config is via environment variables. The MCP client config blocks below show where to set them.

| Variable | Required | Default | Notes | | --- | --- | --- | --- | | UJEX_DEVICE_KEY | yes | — | Agent device key (ap_live_...) or inbox-scoped key (apk_sc_...) from the dashboard. | | UJEX_BASE_URL | no | https://us-central1-axy-ujex.cloudfunctions.net | Firebase Functions base URL. Override for self-hosted Inbox. | | UJEX_AGENT_ID | no | — | Pins a default agent so tool calls don't need agent_id every time. Also enables the postbox://inbox/{id} resource. | | UJEX_FIREBASE_API_KEY | no | Ujex production key | Firebase Web API key used to exchange the session custom token. Override for self-hosted Inbox. | | UJEX_TIMEOUT_MS | no | 30000 | Per-call HTTP timeout in milliseconds. |

Drop-in client configs

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "ujex-postbox": {
      "command": "npx",
      "args": ["-y", "@ujexdev/postbox-mcp"],
      "env": {
        "UJEX_DEVICE_KEY": "ap_live_...",
        "UJEX_AGENT_ID": "agent-hello"
      }
    }
  }
}

Restart Claude Desktop — you should see six postbox_* tools and an inbox resource under the attachments (paperclip) menu.

Cursor

File: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "ujex-postbox": {
      "command": "npx",
      "args": ["-y", "@ujexdev/postbox-mcp"],
      "env": {
        "UJEX_DEVICE_KEY": "ap_live_...",
        "UJEX_AGENT_ID": "agent-hello"
      }
    }
  }
}

Cline (VS Code extension)

In the Cline settings (gear icon -> MCP Servers -> Edit Configuration):

{
  "mcpServers": {
    "ujex-postbox": {
      "command": "npx",
      "args": ["-y", "@ujexdev/postbox-mcp"],
      "env": {
        "UJEX_DEVICE_KEY": "ap_live_...",
        "UJEX_AGENT_ID": "agent-hello"
      }
    }
  }
}

Zed

File: ~/.config/zed/settings.json under context_servers:

{
  "context_servers": {
    "ujex-postbox": {
      "command": {
        "path": "npx",
        "args": ["-y", "@ujexdev/postbox-mcp"],
        "env": {
          "UJEX_DEVICE_KEY": "ap_live_...",
          "UJEX_AGENT_ID": "agent-hello"
        }
      }
    }
  }
}

Tools

All six tools validate input and output with zod. Network errors are surfaced as structured MCP tool errors — the client/model stays in a clean state.

| Tool | Does | | --- | --- | | postbox_send_email | Send an email on behalf of the agent. Supports thread keys, idempotency, and require_human for approval gating. | | postbox_list_messages | List messages (inbound / outbound / both). Each item carries pi_score, pi_reasons, and a {dkim, spf, dmarc} auth verdict. | | postbox_read_message | Fetch one message's full body by id. | | postbox_list_inboxes | Enumerate an agent's mailboxes. Each row carries mail_state, mail_state_reason and ready — provisioning is deferred from agent creation, so full_address may be merely reserved. Check ready before sending. (0.3.0) | | ujex_memory_write / ujex_memory_search | Write and search Markdown memory with a stable run session. | | ujex_identity_passport | Fetch the signed agent passport. | | ujex_approval_request / ujex_approval_get | Request and poll a human decision. | | ujex_audit_list | Read the authenticated agent's audit entries. Human evidence export remains in the owner app. | | postbox_create_plus_address | Local. Derive base+task@domain for per-task tagged addresses. | | postbox_verify_inbound | Local. Timing-safe HMAC-SHA256 verification of an inbound webhook body. |

Resources

| URI | Contents | | --- | --- | | postbox://inbox/{agent_id} | JSON snapshot of the 20 latest inbound messages. Exposed only when UJEX_AGENT_ID is set. |

Development

npm install
npm run typecheck
npm test         # vitest, network mocked
npm run build    # emits dist/

• Strict TypeScript (strict: true, noUncheckedIndexedAccess: true).
• Stdio transport by default; the server is a pure data-in / data-out Node process and can run in any sandbox that allows outbound HTTPS.

Security

• HMAC verification uses node:crypto.timingSafeEqual.
• The device key is sent only to the Ujex session callable, then cached Firebase ID tokens authenticate Inbox callables.
• Tool handlers do not shell out and do not touch the filesystem.

License

Apache-2.0.