MCP (Meta-Controller Protocol) Integration
Relevant source files
The following files were used as context for generating this wiki page:The AI Dev Atelier project leverages the Meta-Controller Protocol (MCP) to extend the capabilities of AI agents with a suite of external tools. This integration provides a production-grade skill pack for tasks like web search, documentation lookup, academic research, and advanced code analysis, enabling agents to perform more complex and context-aware development work. The system is designed to be configurable and extensible through a central mcp.json file.
Sources: README.md:18, AGENTS.md:6
Architecture and Configuration
The MCP integration is defined in the mcp.json file, which acts as a central registry for all available MCP servers. When an agent needs to use a tool provided by an MCP, its runtime consults this configuration to determine how to connect to or launch the required server. The install.sh script automates the process of integrating these server configurations into the agent's environment, particularly for OpenCode agents.
Sources: mcp.json, INSTALL.md:155-163
The following diagram illustrates the high-level architecture of the MCP integration.
This diagram shows how the install.sh script uses mcp.json to configure the agent's runtime, which then connects to various external MCP servers.
Sources: mcp.json, INSTALL.md:112-118
MCP Server Definition
MCP servers are defined in mcp.json and can be one of two types:
- URL-based: The agent connects to a remote server via a URL. API keys are passed in headers.
- Command-based: The agent launches a local process using a specified command and arguments. API keys are passed as environment variables.
Sources: mcp.json:5-12,25-31
Here is an example of a URL-based server definition for Tavily:
"tavily-remote-mcp": {
"_description": "Tavily MCP - Web search and research. Required for 'search' skill.",
"url": "https://mcp.tavily.com/mcp",
"headers": {
"Authorization": "Bearer TAVILY_API_KEY"
}
}
Sources: mcp.json:5-12
And here is an example of a command-based server for OpenAlex:
"openalex-research": {
"_description": "OpenAlex MCP - Academic paper discovery and citation analysis. Required for 'research' skill.",
"command": "npx",
"args": ["-y", "openalex-research-mcp"],
"env": {
"OPENALEX_EMAIL": "you@example.com"
}
}
Sources: mcp.json:25-31
Available MCP Servers
The project pre-defines a set of MCP servers to support various skills. The install.sh script automatically configures these for OpenCode agents.
| MCP Server | Purpose | Required Key / Env Var | Associated Skills |
|---|---|---|---|
tavily-remote-mcp | Web search and research. | TAVILY_API_KEY | search |
context7 | Developer documentation search. | CONTEXT7_API_KEY (optional) | search |
grep | Search across public GitHub repositories. | None | search |
openalex-research | Academic paper discovery and citation analysis. | OPENALEX_EMAIL | research |
pdf-reader | PDF text extraction. | None | research |
paper-search | Multi-platform academic paper search and download. | Optional API keys | research |
zai-zread | GitHub repo semantic search (issues, PRs, docs). | Z_AI_API_KEY | search, research |
zai-vision | Image/video analysis, UI code generation, diagram understanding. | Z_AI_API_KEY | ui-animation, code-review, docs-write, research |
graphite | Stacked PR management. | Graphite CLI must be installed | use-graphite |
Sources: mcp.json, README.md:52-69, AGENTS.md:92-104
Installation and Setup
The install.sh script handles the setup of MCP servers for OpenCode agents. It requires jq to be installed to correctly parse and merge JSON configurations.
The script performs the following steps:
- Reads the MCP server definitions from
mcp.json. - Reads the existing OpenCode configuration from
~/.opencode/opencode.json. - Merges the MCP definitions into the agent's configuration, preserving any existing settings.
- Populates API key placeholders from an
.envfile at the root of the repository.
Sources: INSTALL.md:155-171, README.md:23-25
The installation flow for MCP configuration is as follows:
This diagram shows the process install.sh follows to configure MCPs, highlighting the jq dependency.
Sources: INSTALL.md:52-55, 169-171
Skill Integration
Several skills in AI Dev Atelier are built on top of the MCP framework to perform their tasks. The search and research skills are primary examples.
The diagram below shows which skills depend on which MCP servers.
This diagram illustrates the mapping between skills and the MCPs they utilize.
Sources: skills/README.md:14-45, mcp.json
Z.AI MCP Tool Management
The zai-zread and zai-vision MCPs have specific usage recommendations to manage API quotas and avoid redundancy with native agent tools.
Sources: mcp.json:49-92, AGENTS.md:106-120
Recommended Configuration
It is advised to disable certain Z.AI tools in the agent's configuration (~/.opencode/opencode.json) because free or native alternatives exist.
| Disabled Tool | Reason / Free Alternative |
|---|---|
zai-zread_read_file | Use webfetch on the raw GitHub file URL. |
zai-zread_get_repo_structure | Use gh api repos/{owner}/{repo}/git/trees/{branch}. |
zai-vision_image_analysis | Use the agent's native look_at tool. |
zai-vision_extract_text_from_screenshot | Use the agent's native look_at tool for OCR. |
Sources: mcp.json:57-60, 85-88, AGENTS.md:111-120
To disable these, you would add the following to your ~/.opencode/opencode.json:
{
"tools": {
"zai-zread_read_file": false,
"zai-zread_get_repo_structure": false,
"zai-vision_image_analysis": false,
"zai-vision_extract_text_from_screenshot": false
}
}
Sources: AGENTS.md:109-117
Unique Capabilities
The Z.AI MCPs also provide unique capabilities that are recommended for use:
zai-zread:search_docfor semantic search across a repository's issues, PRs, and documentation.zai-vision:ui_to_artifact(UI screenshot to code),ui_diff_check(compare two UI images), andvideo_analysis.
Sources: mcp.json:54-55, 76-84
Summary
The Meta-Controller Protocol is a cornerstone of the AI Dev Atelier project, providing a standardized and powerful way to enhance AI agents with external tools. Through the mcp.json configuration file and the automated install.sh script, the project offers a rich ecosystem of services for search, research, and code interaction. This extensible architecture allows agents to tackle a wider range of complex development tasks, from conducting academic literature reviews to performing semantic searches across a codebase.
Sources: README.md:18, AGENTS.md:6