sendmux-mcp-setup-x

内容来源：clawhub · 原始地址 · 查看安装指南

原始内容

name: "sendmux-mcp-setup" description: "Connect OpenClaw and other agent clients to hosted or local Sendmux MCP servers for mailbox, sending, and management tools." version: "1.3.0" metadata: openclaw: skillKey: "sendmux-mcp-setup" homepage: "https://github.com/Sendmux/skills" primaryEnv: "SENDMUX_API_KEY" envVars: - name: "SENDMUX_API_KEY" required: false description: "Optional Sendmux API key or scoped agent token used by CLI, SDK, HTTP, or MCP examples." - name: "SENDMUX_MAILBOX_API_KEY" required: false description: "Optional mailbox key for the Mailbox surface in the combined MCP server." - name: "SENDMUX_MANAGEMENT_API_KEY" required: false description: "Optional root key for the Management surface in the combined MCP server." - name: "SENDMUX_MBX_KEY" required: false description: "Optional Sendmux mailbox key for Mailbox and send-capable mailbox workflows." - name: "SENDMUX_MCP_HTTP_BEARER_TOKEN" required: false description: "Optional bearer token expected by the local HTTP MCP server." - name: "SENDMUX_MCP_SURFACES" required: false description: "Optional comma-separated surfaces for the combined Sendmux MCP server." - name: "SENDMUX_ROOT_KEY" required: false description: "Optional Sendmux root key for account-level Management API setup." - name: "SENDMUX_SENDING_API_KEY" required: false description: "Optional send-capable mailbox key or owner-approved agent token for the Sending MCP surface." install: - kind: "uv" package: "sendmux-mcp" bins: - "sendmux-mcp" - "sendmux-mcp-mailbox" - "sendmux-mcp-management" - "sendmux-mcp-sending"

Sendmux MCP setup

ClawHub account note

This ClawHub skill connects OpenClaw agents to Sendmux. Some workflows require a Sendmux account and an appropriate Sendmux API key or agent token. Sendmux account usage is external to ClawHub; do not ask users to paste secrets into chat.

Use this skill to connect an agent client to Sendmux through MCP.

Boundaries

  • Do not ask the user to paste API keys or bearer tokens.
  • Use smx_mbx_ keys or scoped smx_agent_ tokens for Mailbox MCP tools.
  • Use send-capable smx_mbx_ keys or owner-approved Sending-resource smx_agent_ tokens for Sending MCP tools.
  • Use smx_root_ keys for Management MCP tools.
  • Use hosted OAuth at https://mcp.sendmux.ai/mcp when the client supports remote MCP OAuth.
  • Use local stdio when the client cannot use hosted OAuth or local HTTP.
  • For local stdio or HTTP, pass Sendmux keys and owner-approved agent tokens through environment variables backed by the user's secret store; do not write raw tokens into checked-in MCP config.
  • Use local HTTP bearer only for local/private MCP servers; the bearer token protects the MCP endpoint and is separate from the Sendmux API key used upstream.
  • Use server-qualified names such as sendmux-mailbox:mailbox_search_message_snippets when a client needs fully-qualified tool names.

Install

pip install sendmux-mcp

Console scripts:

  • sendmux-mcp — combined local server; requires --surfaces or SENDMUX_MCP_SURFACES.
  • sendmux-mcp-mailbox — mailbox-only local server.
  • sendmux-mcp-management — management-only local server.
  • sendmux-mcp-sending — sending-only local server.
  • sendmux-mcp-hosted — hosted runtime; do not use this for normal local agent setup.

Choose A Setup

Setup Use when Auth
Hosted remote The client supports remote MCP OAuth. Client signs in through Sendmux OAuth; do not pass API keys.
Local stdio The agent runs a local child process. Env vars passed to the server process.
Local HTTP bearer A local/private MCP endpoint is shared by one or more clients. Sendmux API key in server env; Authorization: Bearer ... from client to MCP server.

Surface Map

Surface Key Tool count Example tools
Mailbox smx_mbx_ or scoped smx_agent_ 24 mailbox_list_granted_mailboxes, mailbox_search_message_snippets, mailbox_get_attachment, mailbox_upload_attachment, mailbox_wait_for_message
Management smx_root_ 20 management_create_domain, management_create_mailbox, management_create_mailbox_key, management_get_spend_summary, management_create_webhook
Sending Send-capable smx_mbx_ or owner-approved Sending-resource smx_agent_ 5 sending_send_email, sending_send_email_batch, sending_upload_attachment, sending_create_attachment_upload, sending_get_attachment

For multi-mailbox grants, call mailbox_list_granted_mailboxes first and pass the returned mailbox_id to mailbox tools when targeting a mailbox.

Attachment upload mode depends on transport and send surface:

  • Local stdio can use mailbox_upload_attachment with file_path when the file is inside a client-shared filesystem root.
  • Hosted MCP cannot read local paths. Use presign_upload_url=true, upload with shell curl, then send with the returned blob_id.
  • Sending MCP uses sending_upload_attachment with file_path on local stdio, or sending_create_attachment_upload plus an external PUT for hosted/shell-capable agents, then sends with attachment_id.
  • Use content_base64 only for tiny generated files. Mailbox upload modes cap each attachment at 7,500,000 bytes; Sending upload caps each file at 18 MiB; MCP inline base64 caps at 32 KiB decoded. See sendmux-attachments.

Local Servers

Mailbox-only stdio:

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux-mcp-mailbox

Management-only stdio:

SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux-mcp-management

Sending-only stdio:

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux-mcp-sending

Combined stdio:

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY="$SENDMUX_MBX_KEY" \
SENDMUX_MANAGEMENT_API_KEY="$SENDMUX_ROOT_KEY" \
SENDMUX_SENDING_API_KEY="$SENDMUX_MBX_KEY" \
sendmux-mcp

Local HTTP bearer:

SENDMUX_API_KEY="$SENDMUX_MBX_KEY" \
SENDMUX_MCP_HTTP_BEARER_TOKEN="$SENDMUX_MCP_HTTP_BEARER_TOKEN" \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765 --path /mcp

Client header for that local HTTP server:

Authorization: Bearer $SENDMUX_MCP_HTTP_BEARER_TOKEN

/health returns selected surfaces for local HTTP servers.

Common JSON Clients

Use this shape for Cursor, Cline, and Windsurf/Cascade clients that read an mcpServers object.

Local stdio, one mailbox server:

{
  "mcpServers": {
    "sendmux-mailbox": {
      "command": "sendmux-mcp-mailbox",
      "env": {
        "SENDMUX_API_KEY": "${env:SENDMUX_MBX_KEY}"
      }
    }
  }
}

Local stdio, all three surfaces:

{
  "mcpServers": {
    "sendmux": {
      "command": "sendmux-mcp",
      "args": ["--surfaces", "mailbox,management,sending"],
      "env": {
        "SENDMUX_MAILBOX_API_KEY": "${env:SENDMUX_MBX_KEY}",
        "SENDMUX_MANAGEMENT_API_KEY": "${env:SENDMUX_ROOT_KEY}",
        "SENDMUX_SENDING_API_KEY": "${env:SENDMUX_MBX_KEY}"
      }
    }
  }
}

Local/private HTTP bearer:

{
  "mcpServers": {
    "sendmux-local-http": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SENDMUX_MCP_HTTP_BEARER_TOKEN}"
      }
    }
  }
}

Hosted remote OAuth:

{
  "mcpServers": {
    "sendmux": {
      "url": "https://mcp.sendmux.ai/mcp"
    }
  }
}

Client notes:

  • Cursor: put project config at .cursor/mcp.json or global config at ~/.cursor/mcp.json; Cursor interpolates ${env:NAME} in command, args, env, url, and headers.
  • Cline: use ~/.cline/mcp.json, the Cline MCP UI, or cline mcp; remote setup can ask for URL and headers.
  • Windsurf/Cascade: use ~/.codeium/mcp_config.json or Settings > Tools > Windsurf Settings > Add Server; HTTP config accepts serverUrl or url.

Claude Code

Hosted remote OAuth:

claude mcp add --transport http sendmux https://mcp.sendmux.ai/mcp

Then run /mcp and complete the sign-in flow if prompted.

Local stdio:

claude mcp add --transport stdio \
  --env SENDMUX_API_KEY="$SENDMUX_MBX_KEY" \
  sendmux-mailbox -- sendmux-mcp-mailbox

Local HTTP bearer:

claude mcp add --transport http \
  sendmux-local-http http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer $SENDMUX_MCP_HTTP_BEARER_TOKEN"

Project .mcp.json can also use mcpServers with type, url or command, args, env, and headers.

Codex

Use ~/.codex/config.toml for user-level config.

Local stdio:

[mcp_servers.sendmux_mailbox]
command = "sendmux-mcp-mailbox"
env_vars = ["SENDMUX_API_KEY"]

Run Codex with SENDMUX_API_KEY set to an smx_mbx_ key.

Combined stdio:

[mcp_servers.sendmux]
command = "sendmux-mcp"
args = ["--surfaces", "mailbox,management,sending"]
env_vars = ["SENDMUX_MAILBOX_API_KEY", "SENDMUX_MANAGEMENT_API_KEY", "SENDMUX_SENDING_API_KEY"]

Hosted remote OAuth:

[mcp_servers.sendmux]
url = "https://mcp.sendmux.ai/mcp"
oauth_resource = "https://mcp.sendmux.ai/mcp"

Local HTTP bearer:

[mcp_servers.sendmux_local_http]
url = "http://127.0.0.1:8765/mcp"
bearer_token_env_var = "SENDMUX_MCP_HTTP_BEARER_TOKEN"

VS Code And GitHub Copilot

VS Code stores MCP config in .vscode/mcp.json or user profile mcp.json under servers.

Local stdio:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sendmux-mbx-key",
      "description": "Sendmux mailbox API key",
      "password": true
    }
  ],
  "servers": {
    "sendmuxMailbox": {
      "type": "stdio",
      "command": "sendmux-mcp-mailbox",
      "env": {
        "SENDMUX_API_KEY": "${input:sendmux-mbx-key}"
      }
    }
  }
}

Local HTTP bearer:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sendmux-mcp-token",
      "description": "Sendmux local MCP bearer token",
      "password": true
    }
  ],
  "servers": {
    "sendmuxLocalHttp": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer ${input:sendmux-mcp-token}"
      }
    }
  }
}

Hosted remote OAuth:

{
  "servers": {
    "sendmux": {
      "type": "http",
      "url": "https://mcp.sendmux.ai/mcp"
    }
  }
}

GitHub Copilot CLI can add servers interactively with /mcp add or non-interactively:

copilot mcp add sendmux-mailbox -- sendmux-mcp-mailbox
copilot mcp add --transport http sendmux https://mcp.sendmux.ai/mcp
copilot mcp add --transport http sendmux-local-http http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer $SENDMUX_MCP_HTTP_BEARER_TOKEN"

Gemini CLI

Gemini CLI reads mcpServers from settings.json.

Local stdio:

{
  "mcpServers": {
    "sendmux-mailbox": {
      "command": "sendmux-mcp-mailbox",
      "env": {
        "SENDMUX_API_KEY": "$SENDMUX_MBX_KEY"
      },
      "trust": false
    }
  }
}

Hosted remote OAuth:

{
  "mcpServers": {
    "sendmux": {
      "httpUrl": "https://mcp.sendmux.ai/mcp",
      "trust": false
    }
  }
}

Local HTTP bearer:

{
  "mcpServers": {
    "sendmux-local-http": {
      "httpUrl": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer $SENDMUX_MCP_HTTP_BEARER_TOKEN"
      },
      "trust": false
    }
  }
}

Use /mcp auth sendmux if the hosted remote endpoint needs OAuth authentication.

Verification

After adding the server:

  1. Restart or refresh MCP servers in the client.
  2. Confirm the visible tools match the selected surfaces:
    • Mailbox-only: no management_* or sending_* tools.
    • Management-only: no mailbox_* or sending_* tools.
    • Sending-only: sending_send_email, sending_send_email_batch, and Sending attachment tools.
  3. Run one harmless read tool:
    • Mailbox: mailbox_get_me or mailbox_get_session.
    • Management: management_list_domains with a small limit.
    • Sending: list tools only unless the user confirms a real send.
  4. If local HTTP returns 401, check the client Authorization header against SENDMUX_MCP_HTTP_BEARER_TOKEN.
  5. If the process exits before connecting, check the Sendmux key prefix for the selected surface.

Routing

  • First Sendmux API setup or first call: sendmux-getting-started.
  • Sending body shape or send strategy: sendmux-send-email.
  • Mailbox read, search, sync, triage, or reply: sendmux-mailbox-agent.
  • Attachment file paths, presigned uploads, and download URLs: sendmux-attachments.
  • Account-level management strategy: sendmux-management.
  • Terminal command mechanics: sendmux-cli.
  • Cheapest-call doctrine: sendmux-token-efficient-usage.

本页内容由上游仓库自动镜像，如有疑问请访问原始仓库。