Mastra MCP client: connect agents to remote tools

Setup, step by step

1. Step 1

   Create an agent key

   In the Locus Pro dashboard, open Connect, then API keys, then An agent. Pick the tools, a credit cap per call and an expiry. Store the lcac_ key in your deployment’s secret store.

   export LOCUS_AGENT_CONNECTION="lcac_..."   # agent key, from your secret store
   export LOCUS_MCP_URL="https://api.paywithlocus.com/api/credits/mcp"

2. Step 2

   Install the Mastra MCP package

   Run this in an existing Mastra project. If you are upgrading from @mastra/mcp 1.x, read Mastra’s migration guide first.

   npm install @mastra/mcp@latest

3. Step 3

   Configure the client and the agent

   A url makes Mastra use Streamable HTTP. listTools() returns the tools with names prefixed by the server key, so execute becomes locus_pro_execute.

   import { MCPClient } from '@mastra/mcp'
   import { Agent } from '@mastra/core/agent'
   
   export const locus = new MCPClient({
     id: 'locus-research-prod',
     servers: {
       locus_pro: {
         url: new URL(process.env.LOCUS_MCP_URL!),
         requestInit: {
           headers: { Authorization: `Bearer ${process.env.LOCUS_AGENT_CONNECTION}` },
         },
       },
     },
   })
   
   export const researcher = new Agent({
     id: 'researcher',
     name: 'Researcher',
     instructions: 'Use the Locus tools. Always pass max_credits to execute and report the charge.',
     model: 'openai/gpt-6.1-sol',
     tools: await locus.listTools(),
   })

4. Step 4

   Make a first paid call

   Use any model your Mastra setup supports. The execute result reports credits_charged and credits_balance.

   const response = await researcher.generate(
     'Use firecrawl/map to list the URLs on docs.example.com. Pass max_credits 2 and report the charge.',
   )
   console.log(response.text)

5. Step 5

   Disconnect when the process ends

   Call disconnect() on shutdown, or after a request when you built a client just for that request.

   await locus.disconnect()

Static tools or runtime toolsets: which fits Locus Pro?

Use static tools from listTools() when one agent key serves every request, for example your own research agent. Use runtime toolsets from listToolsets() when the credential changes per request.

Runtime toolsets fit platforms. On the Enterprise plan, create one agent key per customer, build an MCPClient with that customer’s key for the request, and pass its toolsets to generate() or stream(). Each customer’s calls then come from their own balance at base price plus your markup.

How do I gate paid Locus calls in Mastra?

Set requireToolApproval on the server definition. It accepts true, or a function that receives the raw tool name, the arguments and any annotations. Returning true for execute and false for everything else pauses only paid calls, through Mastra’s human-in-the-loop flow.

For agents nobody watches, rely on Locus limits. The per-call cap on the agent key is enforced by Locus and fails a call with agent_connection_call_limit_exceeded. The max_credits argument sets a ceiling for one call, and a call above it fails with nothing charged.

• Agent tool spending controls

Which connection limits apply to MCPClient?

MCPClient speaks the MCP 2026-07-28 revision. On connect it asks the server which revisions it offers and falls back to the older initialize handshake for servers that have not upgraded, so it works with either kind.

The default timeout is 60,000 ms for all servers, and each server can override it. listToolsWithErrors() returns tools plus per-server errors, so you can tell when Locus failed to connect before the agent runs. Set allowedHosts when server URLs come from configuration you do not fully trust.

What does a site research job cost through Locus Pro?

Prices come from the Locus catalog; 1,000 credits equal $1. Prices checked November 10, 2026.

Mapping a site and scraping 20 pages costs at most 1 + 20 x 38.6 = 773 credits, about $0.77. The low end of the scrape range is 1 credit, so the same job can cost as little as 21 credits.

If Firecrawl is the only provider you need, it can cost less per call with your own Firecrawl account and API key. Locus Pro fits when the same agent also needs search, enrichment or data providers, and you want one key and one bill.

• Web scraping API alternatives

Which Locus errors should a Mastra agent expect?

Locus refusals come back as tool results the agent reads. Missing or rejected credentials show up as discovery errors when you list tools.

When should a Mastra agent use Locus Pro?

Use it when the agent calls several paid providers, traffic is uneven, or you resell tool access to customers and need each customer billed from their own balance. Skip it when one provider covers the job at steady volume, or when the tool is your own createTool function.

• Vercel AI SDK MCP setup
• Add Locus to any MCP client
• Locus Pro for platforms