Docs: how to connect an external MCP server (Olostep) to Buzz agents?

[awais-yousaf75]

Motivation

Buzz agents can already spawn MCP servers over stdio (via the persona mcp_servers config / .mcp.json, per buzz-persona and buzz-agent). But there don't seem to be user-facing docs showing how to connect a third-party MCP server to give an agent new capabilities. Anyone wanting to extend an agent with an external tool (web search, scraping, etc.) runs into this — the mechanism exists in code, but there's no worked example to follow.

Proposed solution

Per the contributing guide's recommendation to discuss before opening a PR, I wanted to check whether you'd welcome a short docs contribution showing how to connect an external stdio MCP server to a Buzz agent.

Olostep (web scraping / search / crawl) ships a stdio MCP server (npx -y olostep-mcp, OLOSTEP_API_KEY via env) that's compatible with how Buzz spawns MCP servers, so it works as a real, testable example. This would be documentation only — no code changes. It could be framed generically ("connecting external MCP servers") with Olostep as one worked example, rather than vendor-specific — whichever you'd prefer.

Two questions:

1. Would you welcome this kind of doc, and where should it live?
2. Do you prefer a generic guide with Olostep as an example, or would you rather not include third-party examples in the tree?

Alternatives considered

• A vendor-specific example pack under examples/ — but a generic guide seems more broadly useful and less like promotion.
• Doing nothing and leaving it to users to figure out from the code — but a short doc would lower the barrier for anyone extending an agent with MCP tools.

Additional context

Olostep MCP server: https://github.com/olostep/olostep-mcp-server
Searched open issues and PRs for MCP docs — none found covering how to connect an external MCP server.

[Tony-ooo]

We just hit exactly this gap with open-connector (streamable HTTP MCP with Bearer auth) and filed #4550 for a native fix. While that's open, here is the workaround we use in production (verified against Notion):

Direct HTTP JSON-RPC against the MCP endpoint — same server, same token, same action set as an MCP tool, so it is behaviorally equivalent:

1. tools/list — open-connector exposes 5 tools: list_apps, list_connections, search_actions, get_action_guide, execute_action.
2. list_connections {"service":"notion"} to find your connection (id/profile).
3. search_actions {"query":"create page","service":"notion"} → get_action_guide {"actionId":...} for the input schema/scope/policy.
4. Run every action through execute_action {"actionId":"notion.create_page","input":{...}} — connector action names are not MCP method names; calling tools/call directly with an action name returns "Tool not found".
5. Close the loop with a read-back action (e.g. retrieve_page + retrieve_page_markdown) to verify.

Pitfalls worth knowing:

• parent is a one-of: page_id / data_source_id (a Notion database) / workspace; with a parent you must pass the title via properties, not title.
• Internal integrations cannot create workspace-private pages (400 without a parent), and the parent page/database must be explicitly shared with the integration (404 otherwise — visible in search ≠ writable).
• Keep the token in env, never argv.

This covers HTTP MCP servers. For a stdio-only runtime (e.g. buzz-agent), the equivalent is a small stdio→HTTP bridge shim that speaks MCP over stdio and proxies to the HTTP endpoint. Native injection for preset/custom runtimes is tracked in #4550.