Skip to content

Mastra

Connect Mastra agents to xmcp tools over Streamable HTTP with MCPClient, and run a Mastra agent from an xmcp tool.

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Mastra agents can consume xmcp tools through MCPClient, and an xmcp tool can run a Mastra agent and return its text. The runnable example does both in one process.

Shell

Give a Mastra agent xmcp tools

Protect the xmcp server with a bearer token checked on every request, using the constant-time isBearer middleware from the Flue guide. Connect with MCPClient and send the token through requestInit:

src/connection.ts

Mastra namespaces tools as <server>_<tool>. Pass only the tools the agent should use:

TypeScript

Expose a Mastra agent as an xmcp tool

Run the agent inside an ask-agent tool and forward the request signal. Create and disconnect the MCPClient inside each call so callers never share a connection:

src/agent-client.ts

The agent receives only xmcp_get-shipping-policy, so it cannot call ask-agent recursively.

Errors and cancellation

ask-agent runs the agent once and never resubmits. Model or tool failures and empty replies return one generic tool error. Cancelling the MCP request aborts the in-process model and tool calls.

Testing without a model key

The example's smoke test passes an AI SDK mock model to askAgent. The mock model calls the real xmcp tool and then answers, which exercises the full loop without provider credentials.

Tested versions

@mastra/core 1.83.0 and @mastra/mcp 2.9.0.

One framework to rule them all