docs: improve search entry pages

2026-07-08 20:56:27 +08:00
parent 941a2541eb
commit f531f1ce38
33 changed files with 2132 additions and 17 deletions
@@ -0,0 +1,74 @@
+# How to Configure MCP Tools in nanobot
+
+This guide adds an MCP server to nanobot so the agent can use external tools
+through the Model Context Protocol.
+
+## What you will build
+
+- a working nanobot agent
+- one MCP server entry in `~/.nanobot/config.json`
+- a restricted set of MCP tools exposed to the model
+
+## When to use this
+
+Use MCP when the capability you need already exists as an MCP server, or when
+you want external tools to be managed outside nanobot core.
+
+## Install
+
+```bash
+python -m pip install nanobot-ai
+nanobot onboard --wizard
+nanobot agent -m "Hello!"
+```
+
+Install the MCP server runtime separately. Many examples use `npx`, `uvx`, or a
+remote HTTP endpoint.
+
+## Minimal working example
+
+Add this to `~/.nanobot/config.json`:
+
+```json
+{
+  "tools": {
+    "mcpServers": {
+      "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
+        "enabledTools": ["read_file"]
+      }
+    }
+  }
+}
+```
+
+Restart nanobot and ask a question that requires the MCP tool.
+
+## Production notes
+
+- Prefer `enabledTools` over exposing every tool by default.
+- Use `toolTimeout` for slow MCP operations.
+- Use HTTP MCP only for endpoints you trust.
+- Keep MCP server commands stable and versioned in deployment docs or scripts.
+
+## Security notes
+
+- Stdio MCP starts a local process; review the command before enabling it.
+- HTTP/SSE MCP uses nanobot's SSRF guard.
+- Allow private HTTP MCP hosts only with narrow `tools.ssrfWhitelist` CIDRs.
+- Do not place secrets in command arguments when environment variables or
+  headers can be used.
+
+## Troubleshooting
+
+- Run the MCP command outside nanobot first.
+- Start `nanobot gateway --verbose` and inspect tool registration logs.
+- If an HTTP MCP URL is blocked, check whether it points to loopback or a
+  private address that needs explicit allowlisting.
+
+## Related nanobot docs
+
+- [MCP tools for AI agents](./mcp-tools-for-ai-agents.md)
+- [Configuration: MCP](../configuration.md#mcp-model-context-protocol)
+- [Security](../configuration.md#security)