Claude Agent SDK MCP: add remote tools with a key

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 the agent may call, a credit cap per call and an expiry. The SDK reads keys from the process environment and does not load .env files on its own.

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

2. Step 2

   Install the Agent SDK

   Both packages bundle a native Claude Code binary on supported platforms. Locus's framework reference asks for @anthropic-ai/claude-agent-sdk 0.2.70 or later.

   npm install @anthropic-ai/claude-agent-sdk
   
   # Python
   pip install claude-agent-sdk

3. Step 3

   Add Locus Pro in TypeScript

   The server key in mcpServers becomes part of each tool name. allowedTools auto-approves only the four Locus tools listed. The init message reports whether the server connected.

   import { query } from "@anthropic-ai/claude-agent-sdk";
   
   for await (const message of query({
     prompt: "Get the latest AAPL quote with alphavantage/global-quote. Pass max_credits 10 and report the charge.",
     options: {
       mcpServers: {
         locus_pro: {
           type: "http",
           url: process.env.LOCUS_MCP_URL!,
           headers: { Authorization: `Bearer ${process.env.LOCUS_AGENT_CONNECTION}` },
         },
       },
       allowedTools: [
         "mcp__locus_pro__search_apis",
         "mcp__locus_pro__describe_api",
         "mcp__locus_pro__execute",
         "mcp__locus_pro__get_balance",
       ],
     },
   })) {
     if (message.type === "system" && message.subtype === "init") console.log(message.mcp_servers);
     if (message.type === "result" && message.subtype === "success") console.log(message.result);
   }

4. Step 4

   Or add it in Python

   ClaudeAgentOptions takes the same server config as a dict. Use "http" as the type for servers you pass in code.

   import asyncio
   import os
   from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
   
   async def main():
       options = ClaudeAgentOptions(
           mcp_servers={
               "locus_pro": {
                   "type": "http",
                   "url": os.environ["LOCUS_MCP_URL"],
                   "headers": {"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"},
               }
           },
           allowed_tools=["mcp__locus_pro__*"],
       )
       async for message in query(prompt="What is my Locus balance?", options=options):
           if isinstance(message, ResultMessage) and message.subtype == "success":
               print(message.result)
   
   asyncio.run(main())

5. Step 5

   Check the server status

   A status of connected for locus_pro in the init message means the key works. If it reads failed or needs-auth, fix that before you trust the answer, since Claude can fall back to built-in tools when a server is unavailable.

Agent SDK, Messages API connector or Claude Code: which path fits?

All three reach the same Locus Pro server. They differ in where the MCP client runs and which credential it holds.

• Add Locus to Claude Code

How does allowedTools control Locus calls?

MCP tool names are mcp__, then the server key, two underscores and the tool name. So execute on a server keyed locus_pro becomes mcp__locus_pro__execute. Without permission, Claude sees a tool but cannot call it.

List exact names to auto-approve them. A wildcard such as mcp__locus_pro__* approves every Locus tool. Leave execute out of the list for a read-only agent that may search the catalog and check prices but never spend. Anthropic recommends allowedTools over bypassPermissions, which also turns off most other safety prompts.

Why does the Locus server show needs-auth or failed?

The Agent SDK does not open a browser or run an OAuth flow. If a server asks for authorization and the SDK has no token to send, it reports needs-auth and the run continues without that server. Passing the agent key in headers avoids this.

failed usually means a wrong URL or a network problem. A remote server that drops mid-session goes back to pending while Claude Code reconnects. After five failed attempts it reports failed, and reconnectMcpServer() in TypeScript or reconnect_mcp_server() in Python retries by hand.

How do I cap spend on each Locus call?

Set the per-call cap on the agent key. Locus checks it before the provider is called, and the model cannot change it. A call above it fails with agent_connection_call_limit_exceeded and nothing is charged.

Ask for max_credits in the prompt or system prompt as a second ceiling. Narrow the key’s tool list to the endpoints the agent needs, and remember the plan limit on paid calls a minute: 5 on Free, 15 on Plus, 240 on Enterprise and 1,200 on Enterprise Plus.

• Agent tool spending controls

What does a market-data agent cost through Locus Pro?

Prices come from the Locus catalog; 1,000 credits equal $1. Free calls include search, describe and balance checks. Prices checked November 10, 2026.

A daily brief for 20 tickers with 1 quote and 1 news search each costs 20 x 5.1 + 20 x 30.3 = 708 credits, about $0.71 a day, or $21.24 over 30 days. The Plus plan includes $20 of credits each billing period, which covers about 28 days of that brief.

• Financial data API

Which SDK limits affect paid tool results?

MCP connections time out after 30 seconds by default; MCP_TIMEOUT changes that, and MCP_TOOL_TIMEOUT sets how long a running tool call may take. A tool result over 25,000 tokens is saved to a file and replaced with a pointer to it; MAX_MCP_OUTPUT_TOKENS changes the limit.

Locus returns long results in parts. Ask the agent to read the rest with get_call_result and the call ID instead of repeating the paid call. Tool search is on by default and loads tool definitions only when needed.

When should a Claude agent use Locus Pro?

Use it when the agent needs paid data from several providers and you want one key, one prepaid balance and a ceiling on each call. It also suits agents that run in bursts, since there is no plan minimum.

Skip it when one provider covers the job at steady volume, since that provider can cost less per call with your own account and API key. Skip it too when the tool is your own code; an SDK MCP server defined in your app is simpler there.

• OpenAI Agents SDK MCP setup
• Add Locus to any MCP client
• Locus Pro plans