mcp-usage
Using MCP (Model Context Protocol) servers to extend agent capabilities. Read the configured MCP source for the current server list — never hardcode it. Use when: add MCP, MCP server, connect MCP, mcp
SKILL.mdskills/mcp/parts/mcp-usage/SKILL.md
GitHubmcp-usage — MCP Server Reference
MCP servers extend agent capabilities. Use the runtime's configured MCP source. An evidence label states what was actually called and when — nothing else counts as "live".
When to Use
Task-routed, not a probe ritual. An MCP tool is called when the mapping below names a server
for the task. search_mcp_tools fetches a schema only after choosing a server; do not call it as
a preliminary probe. When prior decisions, project history, or cross-session context could change
the work, use one relevant memory MCP lookup early and continue with further distinct targeted
queries while each closes a concrete gap. There is no fixed per-task search cap; do not fan out
across overlapping indexes without a reason or repeat identical queries. Route workspace search to the current canon (skills/, _memory/, the project folders)
and Memora to broader semantic/project/inbox retrieval; verify Memora's snapshot results against
canonical files. Obsidian is a separate personal vault. Finding no MCP
match is not a violation; state the route and continue. The old mcp-first gate is retired.
Use this skill for:
- Finding which MCP tool fits a task
- Adding a new MCP server
- Troubleshooting MCP connection issues
- Choosing a server and reading its tool schema
Pinging a server — one cheap call, never a per-server sweep
When the ask is "is this MCP alive", call one read-only tool from it
(search_mcp_tools → call_mcp_tool, e.g. list_tables or a single search) and treat a
clean answer as health. A bulk probe of every server is the wrong move: it spawns
all of them, and one slow server alone can need a minute to start. A per-server
sweep once produced a 95-call turn for a single question; the anatomy of that
reproduction is recorded in the workspace's own reports. Two rules come from it:
- An identical
search_mcp_toolsquery returns an identical answer (verified twice, byte for byte). Asking again with the same string is a defect, not a retry; reword or stop. - A vague safety query is a trap.
list tools or status or health or read only or safe non destructivereturns 8 arbitrary tools from 8 servers with"more": 418— includingcloudflare.execute, whose schema saysdestructive: true. Ask for the server you need, not for a property.
Discover current servers
Two files, two different jobs — name the one you read:
| File | Shape | Who reads it |
|---|---|---|
~/.freebuff/mcp.json |
app consent store: {servers: {"<hash>": {configKey, enabled, allowedTools, approvedManifest, credentialBindings}}} |
the Freebuff session's own tool surface |
~/.agents/mcp.json |
{mcpServers: {name: {type, command|url, args, env}}} |
_scripts/mcp-call.py (the bridge) |
A server nobody uses is disabled rather than kept warm. Any counts you read somewhere are dated, not standing state: the list changes, so inspect the live tool surface instead of trusting a record of it.
For a routed MCP task: use the active host's tool definition/schema and inspect the exact
arguments before calling. A visible definition is only tool surface. Verify a successful
operation only when the task depends on that live capability; a general probe is not a prerequisite
for unrelated work. Before saying a capability is live, name the call that proved
it and the date it was made.
Common use cases
Choose the server by role, then inspect the current tool surface and schema. Do not infer availability from the server name alone.
Configuration
Runtime store: ~/.freebuff/mcp.json. The app owns that schema — entries are hash-keyed and carry
the manifest a human approved in the Desktop dialog. Do not hand-edit or rewrite this app-owned
store as an incidental task step. If the task explicitly authorizes a change, use the supported
consent/configuration flow, preserve existing entries, and verify the needed capability through the
active client; configuration alone does not prove the change loaded or works.
Bridge config: ~/.agents/mcp.json, the classic mcpServers object:
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "package-name", "optional-args"],
"env": { "API_KEY": "$ENV_VAR_NAME" }
}
}
}
Adding a new server
Only change a client configuration when the task and active host explicitly authorize that scope. Use the exact client-owned config and its supported consent flow; do not copy settings between clients or store real secrets in tracked configuration. When authorized:
- Identify the exact file and loader for the intended client (table above).
- Add the entry through that client's supported configuration/consent flow.
- Use the client-supported secret binding, such as
$ENV_VAR_NAMEonly where that loader resolves it. - Use JSON-safe forward slashes in Windows paths where required.
- Use the documented reload path only when needed and authorized; verify the specific operation the task depends on. A successful tools/list alone is not a successful service operation.
Loader order
Do not assume a loader order from this skill. Inspect the current runtime configuration; configuration alone does not prove a live server.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Tool not appearing | Binary not installed (npx/uvx/python missing) |
| Env var not resolving | $VAR_NAME must exist in process.env or it won't load |
| Transport mismatch | Server uses stdio but config says sse (or vice versa) |
| Windows path issues | Use forward slashes in JSON paths |
| Server silently fails | Check stderr: npx -y pkg 2>/tmp/mcp-err.log |
| Bridge call exits 3 | Budget refused it — read the reason, batch instead of retrying |
Task → tool mapping (skill ↔ MCP ↔ script)
Three tool layers per domain. Read left to right for your task; a dash means the
layer adds nothing for that domain. Router names are skills in skills/<name>/.
The servers column is illustrative: availability changes, so verify the one you
need instead of trusting a table.
| Domain | Skill router | MCP servers | Scripts / tools |
|---|---|---|---|
| Security & pentest (authorized) | security (+ security-review) |
dnstwist (T), dechonet (V), shodan (V: live ip_lookup 2026-10-17), virustotal (T: starts and lists tools, key rejected 401) |
tools/mcp-cyber/, the local payload and playbook references |
| Reverse engineering | reverse-engineering (+ reverse-api-engineer) |
— | ghidra/ida/radare2 CLIs per parts |
| Browser automation & scraping | browser |
playwright (V: snapshot operation only); browsermcp (T: 86 tools listed, no successful browser operation recorded) | CloakBrowser, browser-harness (tools/) |
| Web research & SERP | research |
searchmcp (research); context7 (library docs); freshcontext |
agent-reach channels |
| OSINT | osint |
osint-tools, maigret (Docker image soxoj/maigret, use format: json) |
agent-reach, a local image-OSINT tool |
| Knowledge & workspace search | review part relevance-scan for targeted prior-art questions (not a universal entry) |
knowledge-rag (workspace text search); memora (memory snapshot search); zvec-grep (code grep); chroma (needs its backing service); sqlite-mcp (source-specific SQL) | grep / rg and local scripts; route by source freshness, avoid duplicate fan-out |
| Documents (md, reports, diagrams) | documents |
— | python-docx (reading), markdown-to-HTML converter, diagram generator |
| Presentations | decks |
— | bento-slides, dashi-ppt, md-slides, slides |
| Images / vision | media part image-generation |
ai-vision (analyze/compare) | local image scripts |
| 3D & game engines | — | blender (C, app required), unity (C, disabled — bridge :8080) | — |
| Telegram (bot + user) | telegram, part telegram-rich-messages |
telegram-mcp-bot (list_chats); telegram-userbot (a real account — read-only, no sends or account writes) |
a local sender script |
| Email & calendar | email |
google-workspace (V 2026-08-24: 121 tools) | — |
| Notes & long-term memory | sessions (parts) |
knowledge-rag (live workspace canon); memora (snapshot and related-memory retrieval; interactive graph not verified live, potentially slow); obsidian (separate personal vault); notion (C) | _memory/ remains canonical |
| Windows desktop control | desktop |
windows-mcp | local PowerShell scripts |
| Databases & SQL | dev |
sqlite-mcp, db-tools (dbs need build.py first) |
— |
| VPN & network | vpn |
dechonet for DNS | local VPN tooling |
| Dev workflow (git, CI, deploy) | dev, ship |
cloudflare (C, remote) | gh CLI, vercel/wrangler CLIs, docker (T: run_command) |
| Reasoning support | — | sequential-thinking (V: 1 tool) | — |
| Tool discovery (find new agents/MCP) | skill-meta parts |
a search-over-MCP server, when enabled | web research routers |
| MCP itself (add/repair/build) | mcp (this router) |
all | _scripts/mcp-call.py bridge (budgeted; works mid-session, no restart) |
| Robot / Arduino | — | robot (T: 23 tools) | a local arduino-mcp project |
Related Skills
desktoppartwindows-env— Windows environment patternsHOSTS.md— the tool surface of this client and how a new host is wired in