Google ADK MCP tools: McpToolset over Streamable HTTP

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. Set the key in your shell or secret manager before you start the agent.

   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 ADK with the MCP extra

   ADK needs Python 3.10 or later for this setup. The mcp extra adds what McpToolset needs.

   pip install "google-adk[mcp]"

3. Step 3

   Define the agent with a spend guard

   McpToolset connects the first time the agent asks for its tools. before_tool_callback runs before every tool call; returning None runs the tool with the possibly changed args, so it can cap max_credits on execute.

   import os
   from google.adk.agents import LlmAgent
   from google.adk.tools.mcp_tool import McpToolset
   from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
   
   CAP = 40  # credits
   
   def cap_paid_calls(tool, args, tool_context):
       if tool.name == "execute":
           args["max_credits"] = min(float(args.get("max_credits") or CAP), CAP)
       return None  # None runs the tool; a dict would replace its result
   
   root_agent = LlmAgent(
       model="gemini-flash-latest",
       name="locus_news_agent",
       instruction="Use only the approved Locus tools. Report the credits each call charged.",
       tools=[
           McpToolset(
               connection_params=StreamableHTTPConnectionParams(
                   url=os.environ["LOCUS_MCP_URL"],
                   headers={"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"},
                   timeout=30,
                   sse_read_timeout=300,
               ),
               tool_filter=["search_apis", "describe_api", "execute", "get_balance"],
           )
       ],
       before_tool_callback=cap_paid_calls,
   )

4. Step 4

   Start the dev UI

   Run adk web from the folder that holds your agent package, in the same shell where you set the variables.

   adk web

5. Step 5

   Make a first paid call

   Name the endpoint and a ceiling. The execute result reports credits_charged and credits_balance.

   Use perplexity/search for this week’s news on EU AI Act enforcement. Pass max_credits 6 and report the charge.

Which Google setup fits Locus Pro?

ADK in Python is the path above. ADK for TypeScript takes the same values in a different shape. The Gemini Interactions API is a separate option where Google calls the server for you.

How do I cap spend on each ADK tool call?

The model writes the max_credits argument, so it can ask for a higher ceiling than you want. The before_tool_callback above rewrites it before the call leaves your process. Return None, not an empty dict: ADK treats any dict, even {}, as a replacement result and skips the tool.

Keep the agent key’s per-call cap too. Locus checks it before the provider is called, so it holds even if the callback has a bug. tool_filter keeps the model to the four Locus tools, which ADK’s own checklist recommends for every McpToolset.

• Agent tool spending controls

Why do Locus calls time out in ADK?

ADK's remote example sets timeout=5 and sse_read_timeout=300. A paid scrape or enrichment can take more than 5 seconds, so this guide sets timeout=30. Raise it further if a slow provider still times out.

Locus returns long results in parts. Have the agent read the rest with get_call_result and the call ID instead of repeating the paid call. Outside adk web, close the toolset with await toolset.close() when you are done.

What does a news-monitoring agent cost through Locus Pro?

Prices come from the Locus catalog; 1,000 credits equal $1. Search, describe and balance checks are free. Prices checked November 10, 2026.

Watching 50 topics a day with 1 Perplexity search each costs 290 credits a day, about $0.29, or $8.70 over 30 days. The same job with Brave news search costs 1,515 credits a day, or $45.45 over 30 days.

• Best web search MCP servers
• AI web search

Which errors show up when ADK calls Locus Pro?

Locus refusals come back as tool results the model can read. ADK also offers on_tool_error_callback for errors raised during a tool call, which is a good place to log and alert.

When should an ADK agent use Locus Pro?

Use it when the agent needs paid data from several providers, such as search, news, enrichment or market data, behind one key with a ceiling on each call. It also fits agents that run in bursts, since there is no plan minimum.

Skip it when Google’s own tools cover the task. Skip it too when one search provider covers the job at steady volume, since a search can cost less per call with your own Perplexity or Brave account and API key.

• Add Locus to Gemini CLI
• Pydantic AI MCP setup
• Locus Pro plans