Skip to main content
Integrate external tools into your agents via Model Context Protocol (MCP) servers or web search.

​
agno/tools/mcp

Connects to a Model Context Protocol (MCP) server, giving agents access to external tools.

​
Config

FieldTypeRequiredDefaultDescription
commandstringConditional—Command to run the MCP server (for stdio transport). Mutually exclusive with url
urlstringConditional—URL for SSE or streamable-http transport. Mutually exclusive with command
transport"stdio" | "sse" | "streamable-http"NoAuto-detectedTransport protocol. Inferred from command (stdio) or url (sse) if not set
envdict[string, Field[string]]No—Environment variables for the server process
headersdict[string, Field[string]]No—Static HTTP headers for remote transports
include_run_context_headersbooleanNofalseForward agent run context as headers (X-User-ID, X-Session-ID, X-Run-ID)
timeout_secondsintegerNo10Connection timeout in seconds
include_toolslist[string]No—Only include these tool names
exclude_toolslist[string]No—Exclude these tool names
tool_name_prefixstringNo—Prefix added to all tool names (avoids collisions)

​
Outputs

FieldTypeDescription
specobjectSerialized MCP tools spec for runtime reconstruction

​
Example — Remote MCP server

provider: agno
resource: tools/mcp
name: my-tools
config:
  url: "https://mcp.example.com/sse"
  headers:
    Authorization:
      provider: pragma
      resource: secret
      name: mcp-token
      field: outputs.TOKEN
  include_run_context_headers: true
  timeout_seconds: 30

​
Example — Local stdio server

provider: agno
resource: tools/mcp
name: local-tools
config:
  command: "npx -y @modelcontextprotocol/server-filesystem /data"
  env:
    API_KEY:
      provider: pragma
      resource: secret
      name: api-key
      field: outputs.API_KEY

​
Dependencies

Depends on: Nothing directly, but env and headers fields on MCP tools support FieldReferences. Depended on by:
  • agno/agent — in the tools list
  • agno/team — in the tools list

​
Notes

  • For MCP tools, you must provide exactly one of command or url.
  • The transport type is auto-detected if not specified: command implies stdio, url implies sse.
  • The include_run_context_headers option forwards the agent’s user ID, session ID, and run ID as HTTP headers to the MCP server.
  • Web search requires the ddgs package, which is automatically included as a pip dependency.