Docs: how to connect an external MCP server (Olostep) to Buzz agents?
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**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.
Contributor guide
Research direction
Read the contributing guide and the existing buzz-persona and buzz-agent documentation, then inspect the persona mcp_servers configuration and .mcp.json examples. Confirm where an external MCP guide should live and whether a generic guide can include Olostep; done means users have a tested stdio setup, environment-variable instructions, and a clear connection example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100