Dual-Mode MCP Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Dual-Mode Model Context Protocol (MCP) Architecture is a specialized framework within Continuous Claude designed to optimize how AI agents interact with external tools and codebases. It prioritizes a massive reduction in token overhead—up to 99.6%—by shifting from manual tool orchestration to structured, CLI-based execution modes. The architecture supports two primary operational patterns: Scripts-Based Execution (the preferred method for complex workflows) and Direct Script Writing (for novel or simple tasks).
By utilizing filesystem discovery and CLI-based parameter passing, this architecture allows agents to discover capabilities via ls and cat commands rather than loading massive JSON schemas into the context window for every interaction. This "progressive disclosure" pattern ensures high-fidelity context preservation while maintaining extremely fast execution times.
Sources: CLAUDE.md:8-10, scripts/SCRIPTS.md:3-8, scripts/SCRIPTS.md:36-45
Core Execution Modes
The Dual-Mode architecture allows the system to pivot between reusable templates and dynamic code generation depending on the complexity of the requirement.
PRIMARY: Scripts-Based Execution
This mode is preferred for multi-step research, cross-validation, and complex data pipelines involving more than two tool calls. It utilizes pre-defined Python scripts in the scripts/ directory that accept CLI arguments via argparse.
- Efficiency: Achieves a 99.6% token reduction and 96% time reduction.
- Workflow: The agent discovers the script (
ls scripts/), reads the USAGE and CLI arguments (cat scripts/script.py), and executes it usinguv run python -m runtime.harness. - Token Impact: Parameter changes via CLI args cost ~110 tokens, compared to ~5,000 for writing a script from scratch.
Sources: CLAUDE.md:38-53, scripts/SCRIPTS.md:47-59
ALTERNATIVE: Direct Script Writing
Used for novel workflows not covered by existing templates or simple single-tool calls.
- Workflow: The agent explores
servers/to find available tools and writes a one-off Python script. - Execution: Scripts are saved to
workspace/(gitignored) and executed via theruntime.harness. - Token Impact: Typically costs ~2,000 tokens due to the need for schema exploration and code generation.
Sources: CLAUDE.md:65-71, scripts/SCRIPTS.md:104-113
Technical Architecture & Components
The system relies on a runtime layer that manages multi-transport connections and auto-generates typed wrappers to ensure safety and consistency.
System Flow
The following diagram illustrates the lifecycle of a tool request through the Dual-Mode architecture:
The diagram shows the decision path between using existing CLI scripts versus generating new ones, flowing through the runtime harness to the appropriate MCP transport.
Sources: CLAUDE.md:73-88, src/runtime/generate_wrappers.py:192-215
Key Components
| Component | Description | Reference |
|---|---|---|
McpClientManager | Singleton manager for lazy-loading MCP connections; supports tool IDs in serverName__toolName format. | CLAUDE.md:92-93 |
harness.py | The execution entry point; handles asyncio initialization, signal handlers, and cleanup. | CLAUDE.md:94 |
generate_wrappers.py | Auto-generates Pydantic models and Python wrappers (servers/) from MCP schemas. | CLAUDE.md:95-97 |
normalize_fields.py | Corrects inconsistent API field casing (e.g., ADO PascalCase normalization) before returning data. | CLAUDE.md:100-101 |
artifact_index.py | Indexes session metadata into a local SQLite Context Graph. | CLAUDE_ONBOARDING.md:46 |
Multi-Transport Support
The architecture is transport-agnostic, allowing seamless interaction with local and remote MCP servers through a unified configuration.
Supported Transports
| Type | Connection Method | Use Case |
|---|---|---|
| stdio | Subprocess (Read/Write) | Local MCP servers and binaries. |
| SSE | Server-Sent Events | Remote servers requiring real-time updates. |
| HTTP | Streamable HTTP | Standard API integrations with header support. |
Sources: CLAUDE.md:120-137, src/runtime/generate_wrappers.py:230-245
Configuration Example
The mcp_config.json file defines the transport parameters for each server:
{
"mcpServers": {
"local_server": {
"type": "stdio",
"command": "python",
"args": ["server.py"]
},
"remote_service": {
"type": "sse",
"url": "https://api.example.com/mcp"
}
}
}
Sources: CLAUDE.md:118-138
Schema Discovery & Safety
To facilitate the generation of discovery configurations without manual entry, the system includes a classification engine that distinguishes between "Safe" and "Dangerous" tools based on naming patterns and descriptions.
Safety Classification Logic
The classify_tool function in src/runtime/generate_test_params.py uses the following rules:
- Dangerous Keywords (Description): Keywords like
delete,truncate, orremovein the description override other signals. - Regex Patterns (Name):
- Safe:
^get_,^list_,^search_,^read_. - Dangerous:
^drop_,^destroy_,^update_,^write_.
- Safe:
Sources: src/runtime/generate_test_params.py:46-126
Discovery Process
The sequence below shows how the system discovers tool schemas and generates test parameters using Claude:
This sequence illustrates the automated classification and parameter generation flow.
Summary
The Dual-Mode MCP Architecture transforms the AI-agent-to-tool interface from a high-overhead schema exchange into a lean, CLI-driven operation. By utilizing a central runtime.harness, multi-transport support, and automated wrapper generation, the system ensures that agents can operate with maximum efficiency while remaining 100% offline-compatible through local alternatives.
Sources: CLAUDE.md:195-205, scripts/README.md:5-10