# How to Mix MCP Servers and Skills in a Single OpenAI Codex Plugin > Learn how to mix MCP servers and skills in one OpenAI Codex plugin by configuring .app.json and organizing custom skills in SKILL.md files. Streamline your plugin development. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-23 --- **Yes, you can mix MCP servers and skills in a single Codex plugin by declaring the MCP configuration in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) while defining custom skills in separate [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files under the `skills/` directory.** The `openai/plugins` repository demonstrates a flexible architecture that does not force you to choose between Model Context Protocol (MCP) servers and custom skill implementations. A single plugin can simultaneously expose structured MCP endpoints for read-heavy operations and ship custom skills for write-heavy or UI-driven workflows, with the Codex agent intelligently routing requests between both mechanisms at runtime. ## Understanding the Three-File Architecture The hybrid pattern relies on three core configuration files that work together to register both MCP capabilities and skill logic. ### Plugin Declaration in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) The root configuration file `plugins//.app.json` declares the plugin to the Codex platform and optionally contains an `mcp` section that points to a remote MCP server using OAuth-authenticated, streaming-HTTP transport. ```json { "name": "vercel", "version": "1.0.0", "description": "Vercel integration – includes an MCP server for read‑only state queries.", "mcp": { "url": "https://vercel.com/api/mcp", "auth": "oauth" } } ``` *(See the full implementation at [`plugins/vercel/.app.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.app.json) in the openai/plugins repository.)* ### Metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) This file provides plugin metadata and explicitly references both the skills included and the MCP server identifier, allowing the platform to discover both components during initialization. ```json { "name": "vercel", "plugin": { "skills": [ "vercel-api", "vercel-cli" ], "mcpServer": "vercel-mcp" } } ``` ### Skill Definitions in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) Each skill resides under `plugins//skills//` and describes triggers, inputs, outputs, and internal scripts. Skills can be designed to prefer MCP tools when available while implementing fallback logic for when the server is unreachable. ```yaml # plugins/vercel/skills/vercel-api/SKILL.md (excerpt) description: | Retrieve Vercel deployment information. The skill first checks whether the `vercel` MCP server provides a `list_deployments` tool. If the tool is unavailable, it falls back to a `curl` request against the Vercel REST API. ``` ## Runtime Integration and Fallback Patterns At runtime, the Codex agent reads the plugin manifest from [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) to discover any MCP-server configuration and registers the skill descriptors from the `skills/` directory simultaneously. This dual registration enables the agent to invoke **MCP tools** for structured data queries while delegating to **skill implementations** for complex operations requiring custom scripts or local processing. When executing a task, the agent evaluates tool availability in the following priority: - **MCP server calls** – Used for read-only, high-level data that benefits from structured MCP tools (e.g., listing Vercel projects or querying deployment status). - **Skill execution** – Used for write-heavy or UI-driven actions that need custom scripts or local processing (e.g., generating a Wix design from a prompt). - **Fallback execution** – When an MCP tool is missing or the server is unreachable, the skill performs the same operation via a direct REST call or local script. ## Real-World Implementation Examples The **Vercel** and **Wix** plugins in the openai/plugins repository demonstrate this mixed-mode pattern in production. ### Vercel Plugin Located at `plugins/vercel/`, this plugin references an MCP server in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for read-only state queries while the `vercel-api` skill handles edge cases where the MCP server is unavailable. The skill definition at [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) explicitly implements the fallback logic to the Vercel REST API. ### Wix Plugin The Wix plugin at `plugins/wix/` bundles MCP server capabilities for eCommerce and CMS operations in its [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), while the `wix-headless` skill at [`plugins/wix/skills/wix-headless/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/SKILL.md) implements a full headless-site workflow independent of the MCP server. This separation allows the skill to handle complex site generation tasks that exceed the scope of the available MCP tools. ## Summary - **Single-plugin hybrid architecture**: Declare MCP servers in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) and skills in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files within the same repository. - **Intelligent runtime routing**: The Codex agent discovers both MCP configurations and skill descriptors, routing requests to the appropriate mechanism based on tool availability and task requirements. - **Robust fallback support**: Skills can check for MCP tool availability and automatically fall back to direct API calls or local scripts when the server is unreachable. - **Production-ready examples**: The Vercel and Wix plugins demonstrate this pattern, combining MCP servers for structured queries with custom skills for complex write operations. ## Frequently Asked Questions ### Can a single plugin use multiple MCP servers? The current architecture supports referencing one MCP server per plugin through the `mcpServer` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). However, a single MCP server can expose multiple tools, and you can combine these with any number of custom skills to achieve comprehensive functionality. ### How does the agent prioritize between MCP tools and skill logic? The agent evaluates the specific operation requested and checks MCP tool availability first for read-only, structured operations. If the relevant MCP tool is unavailable or the operation requires custom processing (such as UI generation or complex writes), the agent invokes the corresponding skill implementation. ### What happens if the MCP server is unreachable? When the MCP server is unreachable, skills implementing fallback logic execute alternative code paths, typically making direct REST API calls using stored credentials or local scripts. This ensures continuity of service even when the MCP infrastructure experiences downtime. ### Do I need separate authentication for MCP servers and skills? Yes, authentication is handled separately. The MCP server configuration in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) specifies OAuth-based authentication for the streaming-HTTP transport, while individual skills may implement their own authentication mechanisms (such as API keys or tokens) for direct REST calls defined in their [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files.