Model Context Protocol (MCP) Setup
Relevant source files
The following files were used as context for generating this wiki page:
Model Context Protocol (MCP) is an external tool integration system within the SuperGemini Framework that provides enhanced capabilities to the Gemini CLI. These capabilities include official documentation lookups, multi-step reasoning engines, UI component generation, and browser automation. MCP servers run as separate processes, extending the AI's reach into external data and local execution environments.
The setup process involves validating prerequisites (primarily Node.js), installing server packages via npm, and configuring the ~/.gemini/.gemini.json file to enable communication between the Gemini CLI and the individual MCP servers.
Sources: CLAUDE.md:213-215, Docs/Reference/mcp-server-guide.md:5-9
MCP Architecture and Core Servers
The framework integrates six core MCP servers that provide specialized functionality. These servers are orchestrated through the MCP Coordinator, which handles server activation and health monitoring based on the user's requirements and command flags.
Core MCP Servers
| Server Name | Primary Function | Key Features |
|---|---|---|
| context7 | Documentation Lookup | Official library docs, framework patterns, and standards. |
| sequential | Reasoning Engine | Multi-step reasoning and complex systematic analysis. |
| magic | UI Generation | Modern UI component generation using 21st.dev patterns. |
| playwright | Browser Automation | E2E testing and browser-based task automation. |
| morphllm | Code Transformation | Pattern-based code editing and token optimization. |
| serena | Semantic Memory | Semantic code understanding and session project memory. |
Sources: CLAUDE.md:216-223, Docs/Reference/mcp-server-guide.md:12-20, Docs/Getting-Started/quick-start.md:38-41
System Workflow
The following diagram illustrates how the SuperGemini Framework coordinates with MCP servers during a request:
The MCP Coordinator activates relevant servers based on specific command flags (e.g., --c7 for Context7) or intelligent detection of the task's complexity.
Sources: Docs/Getting-Started/quick-start.md:46-51, Docs/Reference/README.md:95-103
Installation and Configuration
The installation of MCP components is handled by the SuperGemini terminal executable. It manages file copying, environment validation, and Node.js version checking.
Prerequisites
MCP servers have specific environment requirements that must be met before installation:
- Node.js: Version 16.0.0 or higher is mandatory for most servers.
- Package Manager: npm or yarn must be available for global package installation.
- System Memory: At least 1GB is recommended (2GB+ for complex reasoning tasks).
Sources: Docs/Reference/mcp-server-guide.md:22-26, Docs/Getting-Started/installation.md:37-41
Installation Commands
MCP components can be installed interactively or via specific CLI flags:
# Install all components including MCP
SuperGemini install --profile full --yes
# Install or update ONLY MCP components
SuperGemini install --components mcp --force
# Update existing MCP servers
SuperGemini update
Sources: Docs/Getting-Started/installation.md:91-105, CLAUDE.md:228-230
Configuration Files
The primary configuration for MCP servers is stored in the user's home directory.
| File Path | Description |
|---|---|
~/.gemini/.gemini.json | JSON configuration containing executable paths and arguments for each MCP server. |
~/.gemini/MCP_*.md | Behavioral instructions specifically for MCP server usage. |
~/.gemini/GEMINI.md | Main instruction file that includes MCP @imports. |
Sources: Docs/Getting-Started/installation.md:144-153, Docs/Reference/mcp-server-guide.md:126-128
MCP Server Troubleshooting
MCP failures generally fall into three categories: environment issues, installation failures, and communication timeouts.
Connection Lifecycle
The following sequence diagram shows the communication flow and potential failure points during an MCP server request:
Common Resolutions
| Issue | Resolution Strategy |
|---|---|
| Node.js Incompatibility | Use nvm install node or update via system package manager to 16+. |
| Permission Denied (EACCES) | Configure npm for a user directory (~/.npm-global) or fix /usr/local/lib ownership. |
| Server Timeout | Restart Gemini CLI session; MCP servers restart automatically with the session. |
| Missing Dependencies | Manually run npm install -g @context7/mcp-server or equivalent for the failing server. |
Sources: Docs/Reference/mcp-server-guide.md:30-40, Docs/Reference/mcp-server-guide.md:52-60, Docs/Reference/mcp-server-guide.md:112-115
Advanced Usage and Flags
Users can selectively activate MCP servers to optimize token usage and performance.
# Activate documentation lookup for a specific framework
/sg:analyze src/ --c7
# Enable multi-step reasoning for complex architectural changes
/sg:implement "new feature" --seq
# Generate UI components with Magic and Context7
/sg:index . --magic --c7
Sources: Docs/Reference/README.md:95-103, SuperGemini/Commands/index.toml:13-16
The Model Context Protocol setup is a critical bridge between the SuperGemini Framework and specialized external tools. By ensuring a proper Node.js environment and using the framework's built-in installer, developers can leverage high-fidelity documentation, reasoning, and automation directly within their AI-assisted development workflow.