Connect MCP servers

Plug any MCP server into Scout as a context provider.

Anything with an MCP server plugs into Scout: Linear, GitHub, Notion, Postgres, Stripe, internal tools. Each server becomes one MCPContextProvider, exposes a query_mcp_<slug> tool on Scout, and runs behind a dedicated sub-agent so tool-name collisions across servers stay isolated.

The full reference, including transport details and the Node-in-Docker gotcha, lives in the Scout repo: MCP_CONNECT.md.

Wire up a server

Add an MCPContextProvider entry to _create_mcp_providers() in scout/contexts.py. Secrets come from the process env via getenv(...).

stdio (local subprocess)

MCPContextProvider(
    server_name="linear",
    transport="stdio",
    command="npx",
    args=["-y", "@linear/mcp"],
    env={"LINEAR_API_KEY": getenv("LINEAR_API_KEY", "")},
    model=default_model(),
)

streamable-http

MCPContextProvider(
    server_name="github",
    transport="streamable-http",
    url="https://mcp.github.com/mcp",
    headers={"Authorization": f"Bearer {getenv('GITHUB_TOKEN', '')}"},
    model=default_model(),
)

sse

MCPContextProvider(
    server_name="notion",
    transport="sse",
    url="https://mcp.notion.so/sse",
    model=default_model(),
)

Add the secret to .env, restart Scout, and the new tool shows up:

curl -sS http://localhost:8000/contexts | jq '.[] | select(.id | startswith("mcp_"))'
# { "id": "mcp_linear", "name": "linear", "ok": true, "detail": "mcp: linear (12 tools)" }

Constructor parameters

Parameter	Required for	Description
server_name	all	Derives id=mcp_<server_name> and tool name query_mcp_<server_name>.
transport	all	One of "stdio", "sse", "streamable-http".
command	stdio	Executable on PATH (npx, uvx, python, …).
args	stdio (optional)	CLI args as list[str].
env	stdio (optional)	Env vars passed to the child process.
url	sse, streamable-http	Server URL.
headers	sse, streamable-http (optional)	HTTP headers.
timeout_seconds	optional	Bounds initial connect and each MCP read. Default 30.
mode	optional	ContextMode.default (sub-agent wrap) or ContextMode.tools (flatten onto Scout).

When to pick mode=tools vs mode=default

Mode	What happens	Right when
default	Scout → sub-agent → MCP. Two extra LLM hops, full namespace isolation.	The server has many tools, cryptic names, or names that collide with another MCP server (e.g. search, create_issue).
tools	Server’s tools surface directly on Scout. No extra hops.	The server has few, distinctively-named tools (e.g. get_current_time). Scout can route without help.

asetup() connects on startup regardless of mode. That’s required for tools mode to discover the server’s functions, and it keeps the MCP SDK’s anyio cancel scope on the same task that aclose() will exit on.

Node-based servers in Docker

command must be on PATH inside Scout’s runtime. The ship image bundles Python (uv, uvx, python), so Python MCP servers like uvx --from mcp-server-time mcp-server-time work out of the box. Node-based servers (npx @something/mcp) need Node installed in your deploy image. Add RUN apt-get install -y nodejs npm to the Dockerfile before shipping.

Build your own provider

If your source isn’t covered by an MCP server, write a ContextProvider directly. Four methods: status, astatus, query, aquery. Override aupdate if the source supports writes.

The agno.context.web.provider module is a complete reference implementation.

Troubleshooting

Symptom	Likely cause
/contexts/mcp_<slug>/status returns ok=false	Server unreachable, or initialize() errored. For stdio: check command is on PATH inside the container. For HTTP: curl the URL to confirm it’s live and your headers auth.
Tool calls fail but status is OK	The server declared a tool it doesn’t actually implement. Check MCPContextProvider logs.
Tool list looks stale	Cached at connect time. Restart Scout to re-discover.

For more, see MCP_CONNECT.md.

Next

Deploy Scout to Railway →