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

# Mastra

> Give a Mastra agent a Qubrics mailbox and sending access through MCP.

Use this page to connect a [Mastra](https://mastra.ai) agent to Qubrics so it can read, search, and reply from a mailbox you grant it.

> [!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

* A Mastra project with `@mastra/core` and `@mastra/mcp` installed.
* A Qubrics key for the surface you are calling. Mailbox work needs an `smx_mbx_` key or a scoped `smx_agent_` token.
* Python available in the same runtime if you use the local stdio connection.

## 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 Mastra theme={null}
npm install @mastra/mcp
```

```bash Qubrics MCP theme={null}
pip install --upgrade sendmux-mcp
```

## Connect over local stdio

Mastra launches the server as a child process and passes your key through the process environment.

```typescript mcp/client.ts theme={null}
import { MCPClient } from "@mastra/mcp";

export const mcpClient = new MCPClient({
  id: "sendmux",
  servers: {
    sendmux: {
      command: "sendmux-mcp-mailbox",
      args: [],
      env: {
        QUBRICS_API_KEY: process.env.QUBRICS_MAILBOX_API_KEY!,
      },
    },
  },
});
```

Run more than one surface in a single server by using the `sendmux-mcp` entry point instead:

```typescript theme={null}
sendmux: {
  command: "sendmux-mcp",
  args: [],
  env: {
    QUBRICS_MCP_SURFACES: "mailbox,sending",
    QUBRICS_MAILBOX_API_KEY: process.env.QUBRICS_MAILBOX_API_KEY!,
    QUBRICS_SENDING_API_KEY: process.env.QUBRICS_SENDING_API_KEY!,
  },
}
```

## Connect over private HTTP

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

```bash theme={null}
QUBRICS_API_KEY=smx_mbx_... \
QUBRICS_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765
```

Then point `MCPClient` at it and send the bearer token on every request:

```typescript mcp/client.ts theme={null}
import { MCPClient } from "@mastra/mcp";

export const mcpClient = new MCPClient({
  id: "sendmux",
  servers: {
    sendmux: {
      url: new URL("http://127.0.0.1:8765/mcp"),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.QUBRICS_MCP_HTTP_BEARER_TOKEN}`,
        },
      },
    },
  },
});
```

## Give the tools to an agent

Load the tools once at startup when the key is the same for every request.

```typescript agents/inbox-agent.ts theme={null}
import { Agent } from "@mastra/core/agent";
import { mcpClient } from "../mcp/client";

export const inboxAgent = new Agent({
  id: "inbox-agent",
  name: "Inbox agent",
  instructions: `
    You triage the mailbox you have been granted.
    Search before you read, and quote the message you acted on.
  `,
  model: "openai/gpt-4o",
  tools: await mcpClient.listTools(),
});
```

## Give each user their own mailbox

When the key changes per tenant, per customer, or per agent, build the client at request time and pass its toolsets into the call instead of binding them to the agent.

```typescript theme={null}
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    sendmux: {
      command: "sendmux-mcp-mailbox",
      args: [],
      env: { QUBRICS_API_KEY: tenantMailboxKey },
    },
  },
});

const response = await inboxAgent.stream("What needs a reply today?", {
  toolsets: await mcp.listToolsets(),
});
```

> [!NOTE]
>
> A mailbox-scoped key is the isolation boundary. An agent holding one
> structurally cannot read another tenant's mail, so provision a key per
> mailbox rather than sharing one across tenants.

## 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] No tools appear on the agent
>
> Confirm the surfaces the server started with. `sendmux-mcp` requires
> `QUBRICS_MCP_SURFACES`; the single-surface entry points do not.

> [accordion] The server exits before Mastra connects
>
> 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] Private HTTP returns 401
>
> Send `Authorization: Bearer <QUBRICS_MCP_HTTP_BEARER_TOKEN>` on every
> request through `requestInit.headers`.

> [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/targeting-and-capabilities.md)
>
> Understand targeting, search, threads, and sync.

> [card] [TypeScript SDK](https://sendmux.ai/docs/developer-tools/sdks/typescript.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.