How to Mix MCP Servers and Skills in a Single OpenAI Codex Plugin

Yes, you can mix MCP servers and skills in a single Codex plugin by declaring the MCP configuration in .app.json while defining custom skills in separate 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

The root configuration file plugins/<name>/.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.

{
  "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 in the openai/plugins repository.)

Metadata in .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.

{
  "name": "vercel",
  "plugin": {
    "skills": [
      "vercel-api",
      "vercel-cli"
    ],
    "mcpServer": "vercel-mcp"
  }
}

Skill Definitions in SKILL.md

Each skill resides under plugins/<plugin>/skills/<skill>/ 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.

# 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 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 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 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, while the wix-headless skill at 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 and skills in 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. 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 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 files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}