MCP & Agent Tools
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) and Agent Tools system in Linux Archductor provides a standardized interface for discovery, authentication, and execution of local and remote coding tools. The system allows agents like Codex and Claude to access external capabilities—such as filesystem operations, GitHub interactions, and web search—by bridging the gap between Large Language Models (LLMs) and local environment configurations.
The architecture centers on a discovery mechanism that scans both user-level and project-level configuration files to surface available MCP servers. These servers are then integrated into the agent's running environment via PTY-backed harnesses, where the application parses TUI streams to identify and structure tool calls for the user interface.
MCP Server Discovery and Status
The system maintains awareness of available tools by scanning specific configuration paths based on the active agent provider. Discovery is split between "User" settings (global for the machine) and "Project" settings (specific to the repository workspace).
Configuration Discovery Logic
Linux Archductor looks for MCP server definitions in several formats:
- JSON Configuration: Primarily used by Claude and Cursor.
- TOML Configuration: Primarily used by OpenAI Codex.
The logic iterates through these files, specifically looking for keys under mcpServers (JSON) or [mcp_servers] (TOML) sections.
Sources: crates/core/src/mcp.rs:35-65, crates/core/src/mcp.rs:135-180
The McpStatus Data Model
The McpStatus structure aggregates discovered servers and the availability of provider executables.
| Field | Type | Description |
|---|---|---|
claude_user / claude_project | Vec<McpServer> | Discovered servers for Claude provider. |
codex_user / codex_project | Vec<McpServer> | Discovered servers for Codex provider. |
codex_executable_available | bool | Whether the codex binary is in the system PATH. |
codex_authenticated | bool | Validates if OPENAI_API_KEY or OPENAI_API_TOKEN is set. |
claude_authenticated | bool | Validates if ANTHROPIC_API_KEY is set. |
Sources: crates/core/src/mcp.rs:11-32, crates/core/src/mcp.rs:105-130
Agent Tools Integration
Agents are managed as SessionKind variants, specifically Codex, Claude, and Shell. The system maps these to specific provider settings and UI controls.
Provider Configuration
The application stores configuration for how these agents are launched, including executable paths and provider-specific parameters like Bedrock regions or Vertex project IDs.
UI Session Controls
In the GTK application, users can switch between different tools and models. The session_surface module manages the "Thinking" mode (reasoning levels) and "Model" selection, which are dispatched as control commands to the running agent.
- Reasoning Modes: Support for
low,medium,high, andextra high. - Control Commands: Commands like
/model <name>or/thinking <level>are queued and sent via thearchcarbridge to the active session.
Sources: crates/gtk-app/src/session_surface.rs:885-925, crates/gtk-app/src/session_surface.rs:1015-1045
TUI Tool Call Parsing
When an agent session is running, Linux Archductor monitors the pseudo-terminal (PTY) output. It uses a structured parser to identify when the agent is attempting to use a tool or skill.
Inline Event Identification
The parser looks for specific patterns in the text stream to create CodexInlineEvent objects:
- Tool Calls: Identifies markers like
functions.exec_commandor MCP-prefixed markers likemcp__server__tool. - Skill Announcements: Detects lines starting with "Using [skill]" or "Read SKILL.md".
- File Changes: Parses "Added", "Edited", or "Deleted" summaries into structured line diffs.
Parsing Logic Implementation
Key functions for extracting tool data from raw text:
parse_codex_tool_call(line): Splits tokens to find dotted tool markers (e.g.,web.run).parse_mcp_tool_marker(token): Specifically handles the double-underscore format used by MCP server bridges (mcp__[server]__[name]).parse_codex_event_blocks(text): Collects multi-line output following a tool call header to populate the event body.
Sources: crates/core/src/codex_tui.rs:504-530, crates/core/src/codex_tui.rs:200-245
CLI Tool Management
The linux-archductor CLI provides diagnostic commands to inspect the state of the MCP and Agent system.
| Command | Subcommand | Description |
|---|---|---|
mcp | status | Prints discovered servers for all providers and workspace paths. |
session | start | Launches an agent session with specific harness options (e.g., plan_mode, reasoning_mode). |
repo | doctor | Validates dependencies including gh, codex, and claude. |
CLI Status Output Example
When running mcp status, the CLI groups servers by origin:
- Claude user (
~/.claude.json) - Claude project (
.mcp.json) - Codex user (
~/.codex/config.toml) - Cursor user (
~/.cursor/mcp.json)
Sources: crates/cli/src/main.rs:610-630, crates/cli/src/main.rs:150-180
Summary
The MCP and Agent Tools system establishes a flexible environment where coding agents can interact with the host system. By scanning standardized configuration files and parsing live PTY outputs, Linux Archductor transforms raw agent text into a structured, interactive experience where tool executions are visible, auditable, and configurable. This integration ensures that whether an agent is using a built-in "skill" or a third-party MCP server, the workflow remains consistent across different LLM providers.