Vercel AI SDK tools from MCP with createMCPClient

Setup, step by step

1. Step 1

   Create an agent key on your server

   In the Locus Pro dashboard, open Connect, then API keys, then An agent. Choose the tools, a credit cap per call and an expiry. The key belongs in server-side environment variables only, never in a browser bundle.

   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 AI SDK and its MCP client

   createMCPClient comes from @ai-sdk/mcp. generateText, streamText and the step helpers come from ai.

   npm install ai @ai-sdk/mcp

3. Step 3

   Connect and run a multi-step call

   The http transport is the one the AI SDK recommends for production. stopWhen with isStepCount caps how many tool rounds one request can take, which also caps how many paid calls it can make.

   import { createMCPClient } from "@ai-sdk/mcp";
   import { generateText, isStepCount } from "ai";
   
   const mcp = await createMCPClient({
     transport: {
       type: "http",
       url: process.env.LOCUS_MCP_URL!,
       headers: { Authorization: `Bearer ${process.env.LOCUS_AGENT_CONNECTION}` },
     },
   });
   
   try {
     const tools = await mcp.tools();
     const { text } = await generateText({
       model: "anthropic/claude-sonnet-5.5",
       tools,
       stopWhen: isStepCount(6),
       prompt: "Use brave/web-search for this week's MCP news. Pass max_credits 35 and report the charge.",
     });
     console.log(text);
   } finally {
     await mcp.close();
   }

4. Step 4

   Close the client after a stream

   With streamText, close the MCP client in the onEnd callback, once the model has finished. A long-running server can instead keep one client open for its lifetime.

   import { streamText } from "ai";
   
   const result = await streamText({
     model: "anthropic/claude-sonnet-5.5",
     tools: await mcp.tools(),
     prompt,
     onEnd: async () => {
       await mcp.close();
     },
   });

5. Step 5

   Check the charge

   The execute result reports credits_charged and credits_balance. A balance check through get_balance is free.

   What did the last search cost, and what is my Locus balance?

Which MCP transport should an AI SDK app use for Locus Pro?

Use the built-in http transport. The AI SDK recommends HTTP for production and says stdio is for local servers only. Locus Pro is a remote server over Streamable HTTP.

If you call OpenAI through the Responses API, the OpenAI provider also has a built-in openai.tools.mcp tool. Then OpenAI calls the server, and your key goes to OpenAI.

Which Locus credential belongs in a Next.js or Node app?

An agent key, used only in server code such as a route handler or a background job. createMCPClient supports OAuth through an authProvider, but that flow needs a person to sign in. A server that answers user requests unattended should hold a scoped agent key instead.

Never put the key in client components or anything shipped to the browser. Platforms on the Enterprise plan can create a key per customer and bill each customer from their own balance.

How do I limit paid tool calls per request?

Four controls stack. isStepCount in stopWhen caps tool rounds per request. activeTools narrows which tools the model can pick. toolApproval set to { execute: "user-approval" } turns every paid call into a tool-approval-request that a person must answer before it runs.

On the Locus side, the agent key’s per-call cap is the limit the model cannot change. A call over it fails with agent_connection_call_limit_exceeded. The max_credits argument adds a per-call ceiling, and a call over it fails with nothing charged.

• Agent tool spending controls

Is it safe to turn on maxRetries for paid tools?

Retries are off by default. maxRetries on createMCPClient retries tools/call after transient HTTP and network failures. Results with isError set go back to the model without a retry. The AI SDK warns that retrying tools with side effects can repeat them.

For Locus calls the risk is smaller. An identical execute call within one minute replays the stored result without a new charge. Keep maxRetries at 1 or 2, and check credits_charged in the result.

What does a search feature cost at real traffic?

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

1,000 Brave searches a day through Locus Pro cost 30,300 credits, $30.30 a day. The same traffic on Firecrawl search costs 1,700 credits, $1.70 a day, so the endpoint you pick sets most of the bill.

Locus Pro earns its place when one feature mixes providers, for example search, scraping and enrichment in one agent, and you want one key, one balance and a ceiling on each call.

• Best web search MCP servers
• AI web search

How do Locus errors show up in the AI SDK?

A bad credential fails at createMCPClient with an MCPClientError whose statusCode is 401 or 403. Fix it before retrying. A Locus refusal during a call returns as an MCP result with isError set, which goes back to the model. Errors your code throws appear as tool-error parts in the result steps.

When is Locus Pro the right tool source for an AI SDK app?

Choose it when the app needs several paid providers, traffic is low or uneven, or you want per-call ceilings and one bill.

Choose the provider’s own SDK when one provider covers the feature at steady volume. A Brave search, for example, can cost less per call with your own Brave account and API key.

• MCP vs API vs SDK
• Add Locus to any MCP client
• Locus Pro plans