WEIR
Get a key
Theme

Agno MCP in v3: MCPTools, Headers and Tool Filters

Connect Agno MCP tools to a remote server in v3: MCPTools with a bearer header, include_tools, the lifecycle trap that drops tools, and real X output.


Published · Updated · 6 min read

Cover image: MCP tools in an Agno agent

Agno MCP support is the MCPTools toolkit: point it at a server URL with an Authorization header, then add it to an agent's tools.

This guide is for Python developers on Agno 3. It connects Weir's remote MCP server for public X (Twitter) data, trims the tool list and covers the lifecycle trap that leaves an agent with no tools. We run Weir.

import os
from agno.tools.mcp import MCPTools

weir = MCPTools(
    url="https://api.weirapp.io/mcp",
    headers={"Authorization": f"Bearer {os.environ['WEIR_API_KEY']}"},
    include_tools=["search_x", "get_x_post"],
    timeout_seconds=30,
)

How to connect an Agno MCP client to a remote server

You need Python 3.10 or later, a Weir key and a model key.

  1. Installpip install "agno[mcp]" anthropic
  2. Get a Weir keyCreate one under API keys in your Weir dashboard. Keep it in WEIR_API_KEY.
  3. Set a model keyAgno's Claude model reads ANTHROPIC_API_KEY.
  4. Run the agentOpen MCPTools with async with and call agent.arun(), as below.

As of 24 October 2026, PyPI lists agno 3.1.10, released on 23 October. Its mcp extra adds the MCP SDK 2.x and FastMCP 4, which both need Python 3.10 or later. On our Windows laptop it resolved to 83 packages.

Older posts show MultiMCPTools, which Agno 3.0 removed on 24 August 2026. They may also build StreamableHTTPClientParams for headers. That still works, but headers= is shorter.

Agno MCP example: an X research agent

The script is 24 lines, in two parts. Part one sets up the toolkit:

import asyncio, os
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.mcp import MCPTools

def weir_tools() -> MCPTools:
    return MCPTools(
        url="https://api.weirapp.io/mcp",
        headers={"Authorization": f"Bearer {os.environ['WEIR_API_KEY']}"},
        include_tools=["search_x", "get_x_post"],
        timeout_seconds=30,
    )

Part two opens it, runs the agent and closes the connection:

async def main(question: str) -> None:
    async with weir_tools() as weir:
        agent = Agent(
            model=Claude(id="claude-sonnet-5-5"),
            tools=[weir],
            instructions="Search X with limit 5 or less. Link every post you cite.",
            tool_call_limit=3,
        )
        result = await agent.arun(question)
    print(result.content)

asyncio.run(main("What have @AgnoAgi and @mastra posted about MCP?"))

Three details matter, per Agno's 3.1.10 source:

  • Async only. MCP tools are coroutines, so agent.run() raises "Async tool ... can't be used with synchronous agent.run()".
  • tool_call_limit=3 caps paid calls. Each Weir search is billed, so a loop can't run up your credits.
  • The model reads every text block. Weir sends the JSON result, then a line like "Charged 2 credits; 607 credits left."

Agno MCP tools: lifecycle, filters and names

Agno gives you three ways to open a toolkit. Only one fails loudly:

Pattern If Weir refuses Tool list
async with MCPTools(...) Raises Loaded once
connect() and close() Logs only Loaded once
Unconnected, in tools Logs only Reloaded each run

With the last two, a bad key leaves the agent with no Weir tools. The run still finishes, but nothing was searched.

Agno's MCP docs recommend connect() and close(). We use async with, the only pattern that raises when Weir says no.

Filters match Weir's own names, like search_x:

  • include_tools keeps only the names you list. exclude_tools drops names.
  • A name Weir doesn't list empties the toolkit. Agno logs "Failed to initialize MCP toolkit", even inside async with. A key without Reddit hides every Reddit tool, so include_tools=["search_reddit"] does this.
  • tool_name_prefix="weir" renames search_x to weir_search_x, for when two servers share a name.

Print list(weir.functions) inside the block to see what the agent will get. A default connection lists 44 tools, and each adds its description to the prompt.

What does the agent get back?

To answer, the agent searches each handle. We made both calls through Weir's MCP server on 24 October 2026:

→ search_x {"fromUsers": ["AgnoAgi"], "query": "MCP -filter:nativeretweets",
            "onlyOriginal": true, "limit": 1}
← 0 posts · 1 credit · nextCursor null
→ search_x {"fromUsers": ["mastra"], same filters}
← 1 post · 2 credits · nextCursor set
  2026-10-23  16 likes  1,349 views  @mastra  "New guide on MCP authentication..."

X search returned no original @AgnoAgi post with "MCP" that day. The empty call cost the 1-credit base, and its null cursor means there's nothing more.

Each post arrives with its url, text and counts, so the agent can link every claim.

3credits for both searches above
11credits for a 10-post search
1credit for a search that finds nothing
5,000free Weir credits every month

Weir bills 1 credit per call plus 1 per X post, and failed calls are free. Packs start at $5 for 25,000 credits and never expire, as of October 2026. See our pricing page.

If it doesn't work

This is what Weir sent our curl call with no key, on 24 October 2026:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.weirapp.io/.well-known/
  oauth-protected-resource/mcp", scope="read:social usage:read monitors:read"
{"error":"unauthorized","error_description":"Authorization is required."}

That challenge is for apps that sign in through a browser. A script sends the key instead, and Weir's free GET /v1/whoami checks it. Other errors:

  • "Failed to connect to" in the log, and no tool calls. The connection failed outside async with. Switch to async with to see the real error.
  • "Failed to initialize MCP toolkit". A filter names a tool Weir didn't list: misspelled, prefixed or hidden by your key's scopes.
  • A search times out. Raise timeout_seconds. With server_params, Agno uses the lower of that and the params' timeout.
  • A tool returns 402. Your Weir credits ran out. The model gets "Error from MCP tool", and retrying won't help.

When not to use Weir

  • Your agent has to post or DM on X. Weir is read-only.
  • You want private data. Weir reads public posts, not bookmarks, DMs or home timelines.
  • Price per post matters most. TwitterAPI.io lists $0.15 per 1,000 tweets as of October 2026, less than our $5 pack.
  • You need a guarantee. Weir isn't licensed by X or affiliated with it, so access can change.

FAQ

Does Agno support MCP?

Yes. MCPTools from agno.tools.mcp connects an agent or team to any MCP server over Streamable HTTP or stdio. Standalone SSE still works for old servers, but Agno's docs mark it deprecated.

What happened to MultiMCPTools in Agno?

Agno 3.0 deleted it, along with allow_partial_failure. The release notes say to use one MCPTools per server. Open each one in the same async with block and pass them all in tools.

How do I pass headers to an MCP server in Agno?

Pass headers={...} to MCPTools, as this guide does. Older code puts them in StreamableHTTPClientParams through server_params. For values that change per run, such as a user's token, use header_provider.

Can Agno be an MCP server?

Yes. Agno's docs say AgentOS(agents=[...], mcp=True) serves an MCP endpoint at /mcp, next to the REST API. Its default tools run your agents, teams and workflows, and MCPConfig publishes only the tools you pick.

Sources

All checked on 24 October 2026.

Keep reading