MCP Tools Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Tools Integration standardizes how scoutline discovers, inspects, and invokes multimodal research tools. It provides a unified interface for interacting with different specialized services including web search, document reading, repository exploration, and visual media analysis.
The system uses ZaiMcpClient to manage connections to various MCP servers and translate between internal sanitized tool names and stable public dotted identities. This integration ensures that agents and users can access capabilities across different transports like HTTP and stdio through a consistent command surface.
Sources: packages/scoutline/src/commands/tools.ts:1-12, packages/scoutline/src/lib/mcp-config.ts:5-12, packages/scoutline/tests/mcp-client.test.js:10-25
Architecture and Configuration
The integration organizes tools into four primary server categories. Each category handles a specific domain of investigative research.
| Server Name | Description | Transport |
|---|---|---|
search | Multi-provider web search capabilities | HTTP |
reader | Web page and document content extraction | HTTP |
zread | GitHub repository structure and file reading | HTTP |
vision | Image analysis, OCR, and technical diagram understanding | stdio |
Sources: packages/scoutline/src/lib/mcp-config.ts:8-13, packages/scoutline/src/lib/mcp-config.ts:101-137
Connection Management
The buildMcpCallTemplate function constructs the configuration required to connect to these services. HTTP-based servers (search, reader, zread) utilize bearer token authorization and JSON request bodies. The Vision server uses a stdio transport, typically invoked via npx @z_ai/mcp-server@latest.
The configuration system respects a resolved environment view. This prevents sensitive keys from leaking into the ambient process.env while ensuring tools receive authorized transport credentials.
Sources: packages/scoutline/src/lib/mcp-config.ts:46-95
Tool Discovery and Inspection
Users discover available MCP tools through meta commands that interact with the ZaiMcpClient.
Discovery Flow
The discovery process identifies tools provided by the registered MCP servers.
The diagram shows the sequence from a user request to the projection of internal tool identities into public formats.
Sources: packages/scoutline/src/commands/tools.ts:25-50, packages/scoutline/src/lib/mcp-config.ts:153-167
Metadata Access
The system provides two modes for inspecting tools:
- List Mode: Returns simple tool names (e.g.,
scoutline.zai.search.web_search_prime). - Full Mode: Returns complete tool schemas, including input parameters and output structures. Sensitive information within these schemas is automatically redacted using
redactTool. - TypeScript Mode: Specifically for Code Mode, this outputs TypeScript interfaces derived from the tool definitions.
Sources: packages/scoutline/src/commands/tools.ts:31-50, packages/scoutline/src/commands/tools.ts:58-72
Tool Name Translation
A critical component of the integration is the translation between internal sanitized names used by the Underlying Tooling Control Plane (UTCP) and the public identities exposed to callers.
Translation Logic
The manual segment scoutline.zai is rewritten to scoutline_zai during registration because some transport layers do not support dots in identifiers.
- Public Form:
scoutline.zai.search.web_search_prime - Internal Form:
scoutline_zai.search.web_search_prime
The projectInternalToolName function ensures that users always interact with the stable dotted prefix, regardless of the internal transport requirements.
Sources: packages/scoutline/src/lib/mcp-config.ts:145-167, packages/scoutline/tests/mcp-client.test.js:46-55
Execution and Tool Calling
The callTool function enables the invocation of specific tools using JSON arguments.
Argument Parsing
Arguments are accepted from three sources:
- Inline JSON: Via the
--jsonflag. - Files: Via the
--fileflag or by prefixing the--jsonvalue with@. - Stdin: When the
--stdinflag is used or the process is piped.
The system validates that arguments are plain objects (Record<string, unknown>). It rejects primitives, arrays, and null values to maintain compatibility with MCP specifications.
Sources: packages/scoutline/src/commands/tools.ts:85-134
Invocation Lifecycle
When a tool is called, the client resolves the public name to the internal identity before dispatching the request.
The sequence diagram illustrates the resolution of tool names and the flow of data during a tool call.
Sources: packages/scoutline/src/commands/tools.ts:136-163, packages/scoutline/tests/mcp-client.test.js:105-125
Error Handling and Normalization
The MCP integration normalizes various failure modes into standard ScoutlineError types.
Error Classification
The system classifies errors to determine if an operation should be retried.
| Error Code | Status Code | Condition | Retryable |
|---|---|---|---|
QUOTA_ERROR | 429 | Code 1310 or "limit reached" message | No |
AUTH_ERROR | 401/403 | Credential expired or invalid | No |
API_ERROR | 500-599 | Unexpected system errors or 5xx responses | Yes |
VALIDATION_ERROR | 400 | Invalid request parameters or repository format | No |
Sources: packages/scoutline/tests/mcp-client.test.js:180-210, packages/scoutline/tests/zai-repository-adapter.test.js:520-580
Security and Redaction
To prevent data leakage, the integration scrubs raw provider response bodies. Configuration secrets found in tool outputs or error messages are replaced with [REDACTED] before they reach the user or are persisted to the disk cache.
Sources: packages/scoutline/tests/mcp-client.test.js:212-230, packages/scoutline/tests/mcp-client.test.js:630-670
Specialized Tool Adapters
Certain research capabilities use specialized logic to choose between different execution paths.
Vision Fallback Logic
The Vision system implements an "exhaustion fallback" for OCR tasks. If the high-performance glm-ocr REST service returns a 1113 error (insufficient balance), the system automatically falls back to an MCP-based vision tool. This ensures continuity of service during PAYG balance depletion.
Sources: packages/scoutline/tests/glm-ocr-adapter-routing.test.js:115-135
Repository Exploration (ZRead)
Repository tools utilize specific XML-like wrappers for data extraction:
<excerpt>: Used for code search results.<file_content>: Used for raw file reading.<structure>: Used for directory tree listings.
The adapter validates the integrity of these wrappers and enforces strict indentation rules for tree structures to prevent parsing errors.
Sources: packages/scoutline/tests/zai-repository-adapter.test.js:145-200, packages/scoutline/tests/zai-repository-adapter.test.js:380-450
Conclusion
The MCP Tools Integration provides a robust and secure framework for extensible research capabilities. By abstracting transport details and providing sophisticated name resolution and error normalization, it allows scoutline to function as a reliable agent-first CLI for web and repository investigation.