Model Context Protocol (MCP) Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Model Context Protocol (MCP) integrations within this project provide a standardized framework for AI agents to interact with external tools, documentation, and remote codebases. These integrations are primarily orchestrated through a three-tier architecture comprising built-in services, Claude Code compatible configurations, and skill-embedded protocols. The goal is to enhance the agent's context window with real-time data from web searches, official documentation, and open-source repository analysis.
These integrations enable specialized agents like the librarian and explore to perform high-fidelity research by fetching live documentation, searching across GitHub issues, and retrieving implementation examples. By leveraging MCP, the system maintains a "Senior Staff Engineer" level of expertise, ensuring that decisions are grounded in actual evidence rather than internal model knowledge alone.
Sources: AGENTS.md:143-147, sisyphus-prompt.md:12-23, src/agents/hephaestus.ts:109-115
Architecture and Tiers
The MCP integration follows a structured hierarchy to manage tool discovery and execution.
Tier 1: Built-in MCPs
Built-in MCPs are core services provided directly by the project to facilitate common research tasks.
- Websearch: Integrations with Exa or Tavily for general web discovery.
- Context7: A specialized service for retrieving and querying official documentation.
- Grep App: Used for searching remote GitHub repositories to find implementation patterns.
Tier 2: Claude Code Compatibility
The system supports .mcp.json configuration files. This tier allows for environment variable expansion within the configuration, enabling flexible tool integration that mimics the Claude Code environment.
Tier 3: Skill-Embedded MCPs
Skills within the project can define their own MCP server requirements via YAML frontmatter. This allows specific behaviors (like git-master) to carry their necessary tool contexts.
Sources: AGENTS.md:143-147, sisyphus-prompt.md:112-120
Core MCP Services and Tools
The following table summarizes the primary tools provided through the MCP integrations and their intended usage.
| Service | Tooling Category | Purpose |
|---|---|---|
| Exa / Tavily | websearch | General web queries for latest information and documentation URLs. |
| Context7 | context7 | Resolving library IDs and performing semantic queries against official docs. |
| Grep.app | grep_app | Regex-based search across public GitHub repositories for code patterns. |
| GitHub CLI | gh | Cloning repositories, viewing issues/PRs, and fetching release metadata. |
Sources: src/agents/librarian.ts:167-179, sisyphus-prompt.md:112-120
Document Discovery Workflow
The librarian agent utilizes a specific sequence of MCP calls to ensure documentation accuracy, especially regarding library versions.
The diagram illustrates the sequential logic used by the Librarian agent to discover and query external documentation via MCP tools.
Sources: src/agents/librarian.ts:40-70
Agent Orchestration and Parallel Execution
MCP tools are designed to be executed in parallel to minimize latency during the exploration phase of a task. The atlas and sisyphus agents handle the dispatching of these tools, often firing multiple background tasks simultaneously.
Exploration Hierarchy
Agents follow a strict exploration protocol before requesting human intervention:
- Direct Tools: Utilizing
gh,git, and localgrep. - Explore Agents: Spawning 2-3 parallel background searches using the
exploresubagent. - Librarian Agents: Using MCP-backed web and documentation searches.
- Context Inference: Using surrounding codebase patterns to fill gaps.
Sources: src/agents/hephaestus.ts:208-215, sisyphus-prompt.md:155-165
Parallel Execution Flow
Independent MCP tool calls are grouped to maximize throughput.
This sequence diagram shows how the primary orchestrator manages concurrent calls to MCP services and subagents.
Sources: sisyphus-prompt.md:155-165, src/agents/atlas/gpt.ts:153-165
Implementation Details: The Librarian Agent
The librarian agent is the primary consumer of MCP integrations for external research. It classifies requests into Conceptual, Implementation, Context, or Comprehensive types, each triggering different tool combinations.
Citation and Evidence Protocol
A critical requirement of the MCP integration is the mandatory use of permalinks. Every code claim retrieved via MCP tools must include a GitHub permalink containing the commit SHA and line range.
Permalink Format:
https://github.com/%3Cowner%3E/%3Crepo%3E/blob/%3Ccommit-sha%3E/%3Cfilepath%3E#L<start>-L<end>
Sources: src/agents/librarian.ts:135-155, src/agents/librarian.ts:161-165
Conclusion
MCP integrations serve as the backbone for the project's external awareness. By separating internal codebase exploration (via the explore agent) from external documentation and source analysis (via the librarian agent), the system ensures that AI-generated code remains consistent with modern library standards and existing project patterns. The three-tier architecture provides the flexibility to support both built-in core tools and custom, user-defined MCP servers.