> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CrewAI

> Attach Qubrics mailbox and sending tools to a CrewAI agent or crew.

Use this page to give a [CrewAI](https://www.crewai.com) agent a Qubrics mailbox. `MCPServerAdapter` returns CrewAI tools that map one to one onto the MCP tools your key allows.

> [!WARNING]
>
> 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.
* `crewai` and `crewai-tools` with MCP support installed.
* A Qubrics key for the surface you are calling. Mailbox work needs an `smx_mbx_` key or a scoped `smx_agent_` token.

## Install

> [!WARNING]
>
> Before upgrading an existing installation, keep its working package environment,
> dependency state, and MCP client and tool configuration. Version 2.0.0 removes
> local `file_path` and roots inputs from MCP attachment tools. Before switching
> existing agents, follow the [upgrade and rollback guidance](https://github.com/qubrics/qubrics-sdk/blob/main/packages/python/mcp/README.md#200-upgrade).

```bash theme={null}
pip install crewai "crewai-tools[mcp]"
pip install --upgrade sendmux-mcp
```

## Connect over local stdio

Stdio is the recommended connection for CrewAI, because the adapter passes your key through the subprocess environment.

```python crew.py theme={null}
import os

from crewai import Agent, Crew, Task
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="sendmux-mcp-mailbox",
    args=[],
    env={"QUBRICS_API_KEY": os.environ["QUBRICS_MAILBOX_API_KEY"], **os.environ},
)

with MCPServerAdapter(server_params) as tools:
    triage = Agent(
        role="Inbox triage specialist",
        goal="Find the mail that needs a human today and summarise why",
        backstory="You work one granted mailbox and never guess at content you have not read.",
        tools=tools,
    )

    task = Task(
        description="Review mail received in the last 24 hours and list what needs a reply.",
        agent=triage,
        expected_output="A short list of messages, each with the sender and the reason it needs attention.",
    )

    crew = Crew(agents=[triage], tasks=[task])
    print(crew.kickoff())
```

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

```python theme={null}
server_params = StdioServerParameters(
    command="sendmux-mcp",
    args=[],
    env={
        "QUBRICS_MCP_SURFACES": "mailbox,sending",
        "QUBRICS_MAILBOX_API_KEY": os.environ["QUBRICS_MAILBOX_API_KEY"],
        "QUBRICS_SENDING_API_KEY": os.environ["QUBRICS_SENDING_API_KEY"],
        **os.environ,
    },
)
```

## Limit which tools the crew gets

Pass tool names to the adapter when an agent should only reach part of a surface. A triage agent that never sends is safer than one that could.

```python theme={null}
with MCPServerAdapter(
    server_params,
    "qubrics_mailbox_list_messages",
    "qubrics_mailbox_search_message_snippets",
    "qubrics_mailbox_get_message",
) as tools:
    agent = Agent(role="Inbox triage specialist", goal="Summarise what needs attention", tools=tools)
```

> [!NOTE]
>
> 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.

## Manage the connection yourself

Use manual management when the crew outlives a single block. Always stop the adapter.

```python theme={null}
mcp_server_adapter = MCPServerAdapter(server_params, connect_timeout=60)
try:
    tools = mcp_server_adapter.tools
    agent = Agent(role="Inbox triage specialist", goal="Summarise what needs attention", tools=tools)
    crew = Crew(agents=[agent], tasks=[task])
    crew.kickoff()
finally:
    mcp_server_adapter.stop()
```

## Remote servers

`MCPServerAdapter` also accepts a streamable HTTP server:

```python theme={null}
server_params = {"url": "http://127.0.0.1:8765/mcp", "transport": "streamable-http"}
```

> [!WARNING]
>
> CrewAI does not document custom request headers for its HTTP transports, and
> private HTTP mode requires `QUBRICS_MCP_HTTP_BEARER_TOKEN` unless you start it
> with `--allow-unauthenticated-http`. Use the stdio connection above when the
> crew needs an authenticated Qubrics connection.

## Give each user their own mailbox

Mailbox-scoped keys are the isolation boundary. Build the server parameters per tenant so the crew working one tenant structurally cannot read another tenant's mail.

```python theme={null}
def server_params_for(mailbox_key: str) -> StdioServerParameters:
    credential_names = {
        "QUBRICS_API_KEY",
        "QUBRICS_MAILBOX_API_KEY",
        "QUBRICS_MANAGEMENT_API_KEY",
        "QUBRICS_SENDING_API_KEY",
        "SENDMUX_API_KEY",
        "SENDMUX_MAILBOX_API_KEY",
        "SENDMUX_MANAGEMENT_API_KEY",
        "SENDMUX_SENDING_API_KEY",
    }
    env = {
        name: value
        for name, value in os.environ.items()
        if name not in credential_names
    }
    env["QUBRICS_API_KEY"] = mailbox_key
    return StdioServerParameters(
        command="sendmux-mcp-mailbox",
        args=[],
        env=env,
    )
```

## 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 `QUBRICS_SENDING_API_KEY`.

## Troubleshooting

> [accordion] The adapter returns no tools
>
> Confirm the surfaces the server started with. `sendmux-mcp` requires
> `QUBRICS_MCP_SURFACES`; the single-surface entry points do not.

> [accordion] 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_`.

> [accordion] The process hangs after kickoff
>
> Call `mcp_server_adapter.stop()` in a `finally` block, or use the context
> manager so the connection closes for you.

> [accordion] You granted more than one mailbox
>
> Start the workflow with `qubrics_mailbox_list_granted_mailboxes` and pass the
> returned `mailbox_id` to tools that act on one mailbox.

## Next steps

> [card] [Agent frameworks](https://sendmux.ai/docs/ai-integrations/frameworks)
>
> Compare connections across frameworks.

> [card] [MCP](https://sendmux.ai/docs/ai-integrations/mcp)
>
> Review environment variables and tool discovery.

> [card] [Mailbox API guides](https://sendmux.ai/docs/developer-tools/mailbox-api/operations-and-usage.md)
>
> Understand mailbox operations and usage limits.

> [card] [Python SDK](https://sendmux.ai/docs/developer-tools/sdks/python.md)
>
> Call Qubrics directly when you want full endpoint coverage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.