MCP and Tools

The zqagent runtime can inject external tools through MCP (Model Context Protocol). Built-in OCR works out of the box, and command tools can also be created with /tool add.

Installing MCP Servers

Command	Description
/mcp	List servers, connection status, and tool count
/mcp add	Interactive installation: select a template → fill in parameters → connect and save
/mcp add <name> stdio <cmd...>	Manually add a local process
/mcp add <name> http|sse <url>	Manually add a remote endpoint
/mcp import [file]	Import configuration; if no file is provided, paste JSON and end with EOF
/mcp rm|enable|disable|refresh [name]	Remove / enable / disable / refresh the tool list

Built-in installation templates: Filesystem, Memory, Sequential Thinking, GitHub, Fetch, PostgreSQL, OCR.

Importing Existing Configuration

/mcp import supports bare arrays, { "servers": [...] }, and the mcpServers object format used by Claude Desktop / Cursor:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

• When type is omitted, it is inferred from builtin / url / command; if url ends with /sse, it is inferred as SSE.
• command can be a string and is automatically merged with the args array; ${VAR} / ${env:VAR} environment variable expansion is also supported.
• When saving, entries are written uniformly in array format to .agent/mcp.json (stored with the project and can be committed to git). When importing entries with the same name, you are asked one by one whether to overwrite or skip.

Built-in OCR

Built-in OCR is enabled by default ({ "name": "ocr", "type": "builtin", "builtin": "ocr" }), and the tool name is mcp__ocr__recognize.

• Input: imagePath (recommended, a path within the workspace), imageBase64, imageUrl; PDFs are recognized page by page (maxPages defaults to 5, dpi defaults to 150).
• The engine automatically falls back: macOS Vision (requires Xcode Command Line Tools) → tesseract + pdftoppm → a configured multimodal model.
• If none are available, it returns error and how_to_fix, and does not block startup or other tools.
• To disable it: /mcp disable ocr.

The Linux server image already includes tesseract-ocr, tesseract-ocr-chi-sim, and poppler-utils; in a local environment, you can install them with the system package manager:

# macOS
brew install tesseract tesseract-lang poppler
# Debian / Ubuntu
apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

On-Demand Loading

When there are many MCP tools (by default ≥16 tools or a total schema size ≥24000 characters), it automatically switches to on-demand loading:

• It no longer exposes all mcp__* tools; instead, it uses mcp_search_tools (search) and mcp_call_tool (call);
• The model searches first; matched tools are loaded in the next turn (up to 40 per session), and they can also be called directly via the meta-tools;
• In small-scale scenarios, all tools are still fully injected and behavior is unchanged; ZQAGENT_MCP_LAZY=1|0 can force it on or off.

Command Tools

Command	Description
/tool add <name> <cmd...>	Add a command tool (executes a shell command)
/tool rm|disable|enable <name>	Remove / disable / enable a tool

Immediate Effect and Saving

Adding / removing / disabling / replacing tools takes effect immediately for the next conversation, with no restart required.

The configuration of MCP servers and command tools is saved with the project and can be committed to git and shared with the team. Tools injected by MCP (including built-in OCR) are treated as high-risk by default and require approval each time in interactive mode.

Next Steps

• Built-in tools
• CLI Usage