block / block/buzz

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

Open
#4,515 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.