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

# AI SDK

> Use Qubrics mailbox and sending tools from the AI SDK with generateText or streamText.

Use this page to connect the [AI SDK](https://ai-sdk.dev) to Qubrics. `createMCPClient` converts MCP tools into AI SDK tools, so they drop straight into `generateText` or `streamText`.

> [!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 project with `ai` and `@ai-sdk/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 AI SDK theme={null}
npm install ai @ai-sdk/mcp
```

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

## Connect over private HTTP

HTTP is the better fit for most AI SDK deployments, because serverless and edge runtimes usually cannot spawn a process. Start the server where your key can live:

```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 connect and send the bearer token on every request:

```typescript theme={null}
import { createMCPClient } from "@ai-sdk/mcp";

const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: "http://127.0.0.1:8765/mcp",
    headers: {
      Authorization: `Bearer ${process.env.QUBRICS_MCP_HTTP_BEARER_TOKEN}`,
    },
  },
});
```

## Connect over local stdio

Use this when your process can launch the server itself.

```typescript theme={null}
import { createMCPClient } from "@ai-sdk/mcp";
import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";

const mcpClient = await createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: "sendmux-mcp-mailbox",
    args: [],
    env: { QUBRICS_API_KEY: process.env.QUBRICS_MAILBOX_API_KEY! },
  }),
});
```

## Run the agent

Fetch the tools, pass them to the model, and close the client when the call finishes.

```typescript app/triage.ts theme={null}
import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, isStepCount } from "ai";

let mcpClient;

try {
  mcpClient = await createMCPClient({
    transport: {
      type: "http",
      url: "http://127.0.0.1:8765/mcp",
      headers: {
        Authorization: `Bearer ${process.env.QUBRICS_MCP_HTTP_BEARER_TOKEN}`,
      },
    },
  });

  const tools = await mcpClient.tools();

  const result = await generateText({
    model: "openai/gpt-4o",
    tools,
    stopWhen: isStepCount(5),
    system:
      "You triage the mailbox you have been granted. Search before you read, and quote the message you acted on.",
    prompt: "What arrived overnight that needs a reply?",
  });

  console.log(result.text);
} finally {
  await mcpClient?.close();
}
```

When you stream, close the client in `onEnd` so the connection does not outlive the response:

```typescript theme={null}
const result = await streamText({
  model: "openai/gpt-4o",
  tools,
  prompt: "Summarise today's unread mail.",
  onEnd: async () => {
    await mcpClient.close();
  },
});
```

> [!NOTE]
>
> Spreading several tool sets into one object lets later sets override earlier
> tools with the same name. Keep Qubrics in its own client, or namespace the
> others, when you connect more than one MCP server.

## Give each user their own mailbox

Mailbox-scoped keys are the isolation boundary. Create the client per request with that tenant's key so the agent working one tenant structurally cannot read another tenant's mail. Close it when the request ends.

## 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 start the server with it as `QUBRICS_SENDING_API_KEY`.

## Troubleshooting

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

> [accordion] The HTTP transport returns 401
>
> Send `Authorization: Bearer <QUBRICS_MCP_HTTP_BEARER_TOKEN>` in the
> transport `headers`.

> [accordion] The HTTP transport returns 403 origin\_forbidden
>
> Add the calling origin to `QUBRICS_MCP_ALLOWED_ORIGINS` on the server.

> [accordion] Connections build up under load
>
> Close the client in `finally`, or in `onEnd` when streaming. Every request
> that opens a client has to close one.

## 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/threads.md)
>
> Work with threads and conversation state.

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