paseo-mcp-tools plugin

⚠️ WIP — use at your own risk. Not release-ready; APIs and behavior may change without notice.

Provides an inline UI for checking MCP servers available to an agent session with additional functionality per MCP, such as listing and directly executing MCP tools with auto-generated input forms. Uses the most authoritative list per provider CLI and verifies actual session inclusion with live probes.

(Paseo is an agent orchestrator: AI coding agents run on paseo daemons, each managing workspaces, tools, and permissions.)

Built on paseo-plugin-helper, the shared Paseo plugin runtime.

Screenshots

MCP Servers	Diagnostics	Settings

Server Details	Tool Execution

What it does

Pill above the composer shows MCP n (live servers for that agent). Badge updates via mcp.list, shared between pill and modal.
Live discovery per-CLI via isolated providers/<id>.ts (opencode → opencode mcp list, claude → ~/.claude.json live, antigravity → ~/.gemini/config/mcp_config.json, etc.) + Paseo-injected StoredAgentRecord.mcpServers. Groups by source.label, dedupes by name.
Paseo Built-in Host MCP: Automatically discovers Paseo's host daemon control plane (/mcp/agents?callerAgentId=...) as a first-class MCP server (Paseo (Builtin)), exposing all 60+ live tools (workspaces, browser automation, schedules, terminals, agent orchestration).
Detail & Live Health: Server tap reveals real-time status dots, latency, server instructions, and full tool declarations.
Interactive Tool Runner (User Execution): Users can execute any discovered MCP tool directly from the UI without prompting the agent. Features a dynamic schema-driven form with *REQUIRED validation, type coercion (boolean, number, object, array, union/nullable types), live tool execution via host RPC (mcp.call_tool), and output inspection with 1-tap clipboard copying.
Real-Time Tool Search: Server Detail view features a real-time search input filtering across tool names and descriptions, making servers with large command sets (like Paseo, Forgejo, Chrome DevTools) fast and easy to navigate.
Diagnostics: Full polymorphic probe checklist verifying paths, permissions, and agent records across hosts.

Supported Providers

Provider	Probe Mechanism	Status
Paseo (`paseo`)	Built-in host daemon MCP control plane (`~/.paseo/config.json` + live daemon HTTP session)	Fully tested & verified (60+ tools)
Antigravity (`antigravity`, `antigravity-acp`)	Global `~/.gemini/config/mcp_config.json` + `~/.antigravity/mcp_config.json`	Fully tested & verified
OpenCode (`opencode`)	Live `opencode mcp list` daemon CLI command + config	Fully tested & verified
Pi (`pi`)	User canonical `~/.pi/.mcp.json` / project overrides + heuristics	Fully tested & verified
Claude (`claude`)	User `~/.claude.json` / project `.claude.json` heuristics	Tested against real active configs (without live subscription session)
CodeX (`codex`)	Global `~/.codex/config.toml` / project `.codex/config.toml`	Provided as-is (without guarantees)

Dropping in New Providers

Adding a new tool/CLI probe (e.g. Cursor, Windsurf, Zed, Roo, Cline) is black-box and takes 2 simple steps:

Create providers/<id>.ts declaring candidate config paths using discoverFromCandidates() (or live CLI RPC) with export default <id>Probe.
Add a 1-line re-export to providers/catalog.ts: export { default as <id> } from "./<id>";.

See the complete step-by-step guide in the write-mcp-provider skill (.agents/skills/write-mcp-provider/SKILL.md). Run npm test to automatically verify the probe satisfies the contract.

Layout

File	Owns
`index.ts`	Wiring only: `handle(mcp.list)`, `handle(mcp.read)`, `handle(mcp.health)`, `handle(mcp.call_tool)`, `handle(mcp.diagnose)`, `addClientSide`
`mcp.shared.ts`	zod RPC contracts & shared types (`ToolInfoSchema`, `callMcpTool`, etc.)
`mcp.server.ts`	`discoverLiveServers()`, tool runner execution bridge, and polymorphic diagnostic handlers
`discovery/extract.ts`	Universal heuristic MCP parser (JSON/JSONC, comments, trailing commas, URL safe) & candidate discovery
`discovery/types.ts`	Core contracts (`McpProbe`, `ProbeContext`, `ProbeResult`)
`providers/<id>.ts`	Per-CLI live probe (isolated, contract `McpProbe`: `antigravity.ts`, `claude.ts`, etc.)
`providers/paseo.ts`	Dedicated host daemon probe discovering Paseo control plane & tools
`providers/catalog.ts`	1-line re-export catalog for zero-boilerplate probe registration
`health/health.server.ts`	Generic MCP SDK client (`instructions`, schema-aware `tools`, and `callMcpServerTool`)
`mcp-query.client.tsx`	`useMcpQuery` shared pill/modal, 30m timer + manual Refresh
`pill.client.tsx`	Pill, modal, server details, diagnostics, real-time search, and interactive Tool Runner UI
`scripts/version.mjs`	Offline build-time version stamper (tag / beta-[hash])
`docs/TEST_METHODOLOGY.md`	Test procedures, adapter verification, and QA methodology

Install & Updates

Install from npm:

paseo plugin add npm:@xpufx/paseo-mcp-tools

Or install directly from the Git repository:

paseo plugin add xpufx/paseo --path plugins/mcp-tools

To update or reload the installed plugin:

# update to the latest release
paseo plugin update mcp-tools

# reload the daemon process after local edits
paseo plugin reload mcp-tools

pluginsEnabled: true required. Use paseo plugin logs mcp-tools for diagnostics and runtime logs. Failed reload stays failed (Paseo doesn't restore).

mcp-tools

Gallery

Install