MCP CLI

Default Configuration: MCP CLI defaults to using Ollama with thegpt-ossreasoning model for local, privacy-focused operation without requiring API keys.

- --vmflag: Enable OS-style virtual memory for conversation context management, powered bychuk-ai-session-manager
- --vm-budget: Control token budget for conversation events (system prompt is uncapped on top), forcing earlier eviction and page creation
- --vm-mode: Choose VM mode —passive(runtime-managed, default),relaxed(VM-aware conversation), orstrict(model-driven paging with tools)
- /memorycommand: Visualize VM state during conversations — page table, working set utilization, eviction metrics, TLB stats (aliases:/vm,/mem)
- Multimodal page_fault: Image pages return multi-block content (text + image_url) so multimodal models can re-analyze recalled images
- /memory page <id> --download: Export page content to local files with modality-aware extensions (.txt, .json, .png)

- Interactive HTML UIs: MCP servers can serve interactive HTML applications (charts, tables, maps, markdown viewers) that render in your browser
- Sandboxed iframes: Apps run in secure sandboxed iframes with CSP protection
- WebSocket bridge: Real-time bidirectional communication between browser apps and MCP servers
- Automatic launch: Tools with_meta.uiannotations automatically open in the browser when called
- Session reliability: Message queuing, reconnection with exponential backoff, deferred tool result delivery

- Secret Redaction: All log output (console and file) is automatically redacted for Bearer tokens, API keys, OAuth tokens, and Authorization headers
- Structured File Logging: Optional--log-fileflag enables rotating JSON log files (10MB, 3 backups) at DEBUG level
- Per-Server Timeouts: Server configs supporttool_timeoutandinit_timeoutoverrides, resolved per-server → global → default
- Thread-Safe OAuth: Concurrent OAuth flows serialized withasyncio.Lockand copy-on-write header mutation
- Server Health Monitoring:/healthcommand, health-check-on-failure diagnostics, optional--health-intervalbackground polling

- O(1) Tool Lookups: Indexed tool lookup replacing O(n) linear scans
- Cached LLM Tool Metadata: Per-provider caching with automatic invalidation
- Startup Progress: Real-time progress messages during initialization
- Token Usage Tracking: Per-turn and cumulative tracking with/usagecommand (aliases:/tokens,/cost)
- Session Persistence: Save/load/list conversation sessions with auto-save every 10 turns (/sessions)
- Conversation Export: Export conversations as Markdown or JSON with metadata (/export)

- --dashboardflag: Launch a real-time browser dashboard alongside chat mode
- Agent Terminal: Live conversation view with message bubbles, streaming tokens, and attachment rendering
- Activity Stream: Tool call/result pairs, reasoning steps, and user attachment events
- Plan Viewer: Visual execution plan progress with DAG rendering
- Tool Registry: Browse discovered tools, trigger execution from the browser
- Config Panel: View and switch providers, models, and system prompt
- File Attachments: "+" button for browser file upload, drag-and-drop, and clipboard paste

- /attachcommand: Stage files for the next message — images, text/code, and audio (aliases:/file,/image)
- --attachCLI flag: Attach files to the first message (repeatable:--attach img.png --attach code.py)
- Inline@file:references: Mention@file:path/to/fileanywhere in a message to attach it
- Image URL detection: HTTP/HTTPS image URLs in messages are automatically sent as vision content
- Supported formats: PNG, JPEG, GIF, WebP, HEIC (images), MP3, WAV (audio), plus 25+ text/code extensions
- Dashboard rendering: Image thumbnails, expandable text previews, audio players, file badges
- Browser upload: "+" button in dashboard chat input with drag-and-drop and clipboard paste support

The MCP CLI is built on a modular architecture with clean separation of concerns:

- Chat Mode: Conversational interface with streaming responses and automated tool usage (default: Ollama/gpt-oss)
- Interactive Mode: Command-driven shell interface for direct server operations
- Command Mode: Unix-friendly mode for scriptable automation and pipelines
- Direct Commands: Run individual commands without entering interactive mode

- Streaming Responses: Real-time response generation with live UI updates
- Reasoning Visibility: See AI's thinking process with reasoning models (gpt-oss, GPT-5, Claude 4.5)
- Concurrent Tool Execution: Execute multiple tools simultaneously while preserving conversation order
- Smart Interruption: Interrupt streaming responses or tool execution with Ctrl+C
- Performance Metrics: Response timing, words/second, and execution statistics
- Rich Formatting: Markdown rendering, syntax highlighting, and progress indicators
- Token Usage Tracking: Per-turn and cumulative API token usage with/usagecommand
- Multi-Modal Attachments: Attach images, text files, and audio to messages via/attach,--attach,@file:refs, or browser upload
- Session Persistence: Auto-save and manual save/load of conversation sessions
- Conversation Export: Export to Markdown or JSON with metadata and token usage

MCP CLI supports all providers and models from CHUK-LLM, including cutting-edge reasoning models:

Robust Tool System (Powered by CHUK Tool Processor v0.22+)

- Automatic Discovery: Server-provided tools are automatically detected and catalogued
- Provider Adaptation: Tool names are automatically sanitized for provider compatibility
- Production-Grade Execution: Middleware layers with timeouts, retries, exponential backoff, caching, and circuit breakers
- Multiple Execution Strategies: In-process (fast), isolated subprocess (safe), or remote via MCP
- Concurrent Execution: Multiple tools can run simultaneously with proper coordination
- Rich Progress Display: Real-time progress indicators and execution timing
- Tool History: Complete audit trail of all tool executions
- Middleware: Retry with exponential backoff, circuit breakers, and rate limiting via CTP
- Streaming Tool Calls: Support for tools that return streaming data

- Browser-based UIs: MCP servers can serve interactive HTML applications that render in your browser
- Automatic Detection: Tools with_meta.uiannotations automatically launch browser apps on tool call
- Sandboxed Execution: Apps run in secure sandboxed iframes with Content Security Policy protection
- WebSocket Bridge: Real-time JSON-RPC bridge between browser apps and MCP tool servers
- Session Persistence: Message queuing during disconnects, automatic reconnection, deferred tool result delivery
- structuredContent Support: Full MCP spec compliance including structured content extraction and forwarding

Execution Plans (Powered by chuk-ai-planner)

- Plan Creation: Generate execution plans from natural language descriptions using LLM-based plan agents
- Model-Driven Planning: With--plan-tools, the LLM autonomously decides when to plan — callsplan_create_and_executefor complex multi-step tasks, uses regular tools for simple ones
- DAG Execution: Plans are directed acyclic graphs — independent steps run in parallel batches, dependent steps wait
- Variable Resolution: Step outputs bind to variables (result_variable), referenced by later steps as${var}or${var.field}
- Dry-Run Mode: Trace what a plan would do without executing any tools — safe for production
- Checkpointing: Execution state saved after each batch; resume interrupted plans without re-running completed steps
- Guard Integration: Plans share budget and per-tool limits with the conversation — no bypass
- Re-planning: On step failure, optionally invoke the LLM to generate a revised plan for remaining work
- DAG Visualization: ASCII rendering shows dependency structure, batch grouping, and parallel markers
- Persistence: Plans stored as JSON at~/.mcp-cli/plans/

- Environment Integration: API keys and settings via environment variables
- File-based Config: YAML and JSON configuration files
- User Preferences: Persistent settings for active providers and models
- Validation & Diagnostics: Built-in provider health checks and configuration validation

- Cross-Platform Support: Windows, macOS, and Linux with platform-specific optimizations via chuk-term
- Rich Console Output: Powered by chuk-term with 8 built-in themes (default, dark, light, minimal, terminal, monokai, dracula, solarized)
- Advanced Terminal Management: Cross-platform terminal operations including clearing, resizing, color detection, and cursor control
- Interactive UI Components: User input handling through chuk-term's prompt system (ask, confirm, select_from_list, select_multiple)
- Command Completion: Context-aware tab completion for all interfaces
- Comprehensive Help: Detailed help system with examples and usage patterns
- Graceful Error Handling: User-friendly error messages with troubleshooting hints

Comprehensive documentation is available in thedocs/directory:

- Python 3.11 or higher
- For Local Operation (Default):

- OpenAI:OPENAI_API_KEYenvironment variable (for GPT-5, GPT-4, O3 models)
- Anthropic:ANTHROPIC_API_KEYenvironment variable (for Claude 4.5, Claude 3.5)
- Azure:AZURE_OPENAI_API_KEYandAZURE_OPENAI_ENDPOINT(for enterprise GPT-5)
- Google:GEMINI_API_KEY(for Gemini models)
- Groq:GROQ_API_KEY(for fast Llama models)
- Custom providers: Provider-specific configuration
- Install Ollama(if not already installed):

# macOS/Linux curl -fsSL https://ollama.ai/install.sh | sh # Or visit https://ollama.ai for other installation methods

ollama pull gpt-oss # Open-source reasoning model with thinking visibility

Chat mode provides the most advanced interface with streaming responses and intelligent tool usage.

# Simple startup with default reasoning model (gpt-oss) mcp-cli --server sqlite # Multiple servers mcp-cli --server sqlite,filesystem # With advanced reasoning models mcp-cli --server sqlite --provider openai --model gpt-5 mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus

/provider # Show current configuration (default: ollama) /provider list # List all providers /provider config # Show detailed configuration /provider diagnostic # Test provider connectivity /provider set ollama api_base http://localhost:11434 # Configure Ollama endpoint /provider openai # Switch to OpenAI (requires API key) /provider anthropic # Switch to Anthropic (requires API key) /provider openai gpt-5 # Switch to OpenAI GPT-5 # Custom Provider Management /provider custom # List custom providers /provider add localai http://localhost:8080/v1 gpt-4 # Add custom provider /provider remove localai # Remove custom provider /model # Show current model (default: gpt-oss) /model llama3.3 # Switch to different Ollama model /model gpt-5 # Switch to GPT-5 (if using OpenAI) /model claude-4-5-opus # Switch to Claude 4.5 (if using Anthropic) /models # List available models for current provider

/tools # List available tools /tools --all # Show detailed tool information /tools --raw # Show raw JSON definitions /tools call # Interactive tool execution /toolhistory # Show tool execution history /th -n 5 # Last 5 tool calls /th 3 # Details for call #3 /th --json # Full history as JSON

Server Management (Runtime Configuration)

/verbose # Toggle verbose/compact display (Default: Enabled) /confirm # Toggle tool call confirmation (Default: Enabled) /interrupt # Stop running operations /server # Manage MCP servers (see Server Management above) /help # Show all commands /help tools # Help for specific command /exit # Exit chat mode

Streaming Responses with Reasoning Visibility

- 🧠 Reasoning Models: See the AI's thinking process with gpt-oss, GPT-5, Claude 4
- Real-time Generation: Watch text appear token by token
- Performance Metrics: Words/second, response time
- Graceful Interruption: Ctrl+C to stop streaming
- Progressive Rendering: Markdown formatted as it streams

- Automatic tool discovery and usage
- Concurrent execution with progress indicators
- Verbose and compact display modes
- Complete execution history and timing

- Attach images, text files, and audio to any message
- /attachcommand with staging, list, and clear (aliases:/file,/image)
- Inline@file:pathreferences in any message
- --attachCLI flag for first-message attachments
- Browser "+" button with drag-and-drop and clipboard paste (with--dashboard)
- Dashboard renders thumbnails, text previews, and audio players

- Seamless switching between providers
- Model-specific optimizations
- API key and endpoint management
- Health monitoring and diagnostics

Interactive mode provides a command shell for direct server interaction.

help # Show available commands exit # Exit interactive mode clear # Clear terminal # Provider management provider # Show current provider provider list # List providers provider anthropic # Switch provider provider openai gpt-5 # Switch to GPT-5 # Model management model # Show current model model gpt-oss # Switch to reasoning model model claude-4-5-opus # Switch to Claude 4.5 models # List available models # Tool operations tools # List tools tools --all # Detailed tool info tools call # Interactive tool execution # Server operations servers # List servers ping # Ping all servers resources # List resources prompts # List prompts