Google ADK

Use this page to give a Google Agent Development Kit agent a Sendmux mailbox. McpToolset retrieves MCP tools as ADK tools, and the framework loads and closes them around each agent invocation.

Replace placeholder keys and tokens before running any snippet. Do not commit smx_root_, smx_mbx_, or private HTTP bearer tokens to version control.

Requirements

Python 3.10 or newer.
google-adk installed.
A Sendmux key for the surface you are calling. Mailbox work needs an smx_mbx_ key or a scoped smx_agent_ token.

Install

pip install google-adk sendmux-mcp

Connect over local stdio

The toolset launches the server and passes your key through the subprocess environment.

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from mcp import StdioServerParameters

sendmux_toolset = McpToolset(
    connection_params=StdioServerParameters(
        command="sendmux-mcp-mailbox",
        args=[],
        env={"SENDMUX_API_KEY": os.environ["SENDMUX_MAILBOX_API_KEY"]},
    ),
)

root_agent = LlmAgent(
    name="inbox_agent",
    instruction=(
        "You triage the mailbox you have been granted. "
        "Search before you read, and quote the message you acted on."
    ),
    tools=[sendmux_toolset],
)

Run more than one surface by switching to the sendmux-mcp entry point:

connection_params=StdioServerParameters(
    command="sendmux-mcp",
    args=[],
    env={
        "SENDMUX_MCP_SURFACES": "mailbox,sending",
        "SENDMUX_MAILBOX_API_KEY": os.environ["SENDMUX_MAILBOX_API_KEY"],
        "SENDMUX_SENDING_API_KEY": os.environ["SENDMUX_SENDING_API_KEY"],
    },
)

Connect over private HTTP

Use this when the agent runs somewhere it cannot spawn a process. Start the server yourself:

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765

Then connect with streamable HTTP connection parameters:

import os

from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset

sendmux_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="http://127.0.0.1:8765/mcp",
        headers={
            "Authorization": f"Bearer {os.environ['SENDMUX_MCP_HTTP_BEARER_TOKEN']}"
        },
    ),
)

Narrow what the agent can reach

tool_filter limits the toolset to named tools. A triage agent that never sends is safer than one that could.

sendmux_toolset = McpToolset(
    connection_params=StdioServerParameters(
        command="sendmux-mcp-mailbox",
        args=[],
        env={"SENDMUX_API_KEY": os.environ["SENDMUX_MAILBOX_API_KEY"]},
    ),
    tool_filter=[
        "mailbox_list_messages",
        "mailbox_search_message_snippets",
        "mailbox_get_message",
    ],
)

Open your MCP tool listing after connecting to confirm the exact names your key exposes. Tool names are generated from the current public API surfaces.

Give each user their own mailbox

Mailbox-scoped keys are the isolation boundary. Build a toolset per tenant so the agent working one tenant structurally cannot read another tenant’s mail.

def toolset_for(mailbox_key: str) -> McpToolset:
    return McpToolset(
        connection_params=StdioServerParameters(
            command="sendmux-mcp-mailbox",
            args=[],
            env={"SENDMUX_API_KEY": mailbox_key},
        ),
    )

For a per-request key over private HTTP, supply header_provider instead. It runs at session creation and merges its headers into every tool call.

Sending stays gated

A durable smx_agent_ token includes mailbox.read and email.receive, not email.send. After a named human owner accepts the invite and approves sending, exchange the durable token for a one-hour Sending-resource token and pass that as SENDMUX_SENDING_API_KEY.

Troubleshooting

The agent sees no tools

Confirm the surfaces the server started with. sendmux-mcp requires SENDMUX_MCP_SURFACES; the single-surface entry points do not. Check tool_filter as well, since it hides everything it does not name.

The subprocess exits immediately

Check the key prefix. Mailbox accepts smx_mbx_ or a scoped smx_agent_, Sending accepts a send-capable smx_mbx_ or an owner-approved Sending-resource smx_agent_, and Management requires smx_root_.

A stdio server is refused when loaded from agent config

ADK blocks stdio MCP servers declared in external agent configuration unless you set ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS=1. Define the toolset in code, or opt in only for configurations you trust.

Private HTTP returns 401

Send Authorization: Bearer <SENDMUX_MCP_HTTP_BEARER_TOKEN> through headers or header_provider.

Next steps

Agent frameworks

Compare connections across frameworks.

MCP

Review environment variables and tool discovery.

A2A

Reach Sendmux through an A2A agent endpoint.

Python SDK

Call Sendmux directly when you want full endpoint coverage.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Requirements

Install

Connect over local stdio

Connect over private HTTP

Narrow what the agent can reach

Give each user their own mailbox

Sending stays gated

Troubleshooting

Next steps

Agent frameworks

MCP

A2A

Python SDK

​Requirements

​Install

​Connect over local stdio

​Connect over private HTTP

​Narrow what the agent can reach

​Give each user their own mailbox

​Sending stays gated

​Troubleshooting

​Next steps

Agent frameworks

MCP

A2A

Python SDK

Requirements

Install

Connect over local stdio

Connect over private HTTP

Narrow what the agent can reach

Give each user their own mailbox

Sending stays gated

Troubleshooting

Next steps