What Are MCP Servers in Codex Plugins and How to Configure Them

MCP (Model Context Protocol) servers in Codex plugins are standardized HTTP endpoints that expose JSON schema-based tool definitions, enabling AI agents to discover and invoke platform capabilities without hard-coded API calls or exposed secrets.

In the openai/plugins repository, MCP servers provide the bridge between AI agents and third-party platforms like Wix, Render, and Vercel. They replace static API integrations with dynamic, discoverable tool catalogs that handle authentication, versioning, and schema validation automatically.

Understanding MCP Servers in Codex Plugins

An MCP server acts as a capability broker for AI agents. Instead of embedding API logic directly into agent prompts, plugins declare an MCP server that exposes a catalog of available tools.

According to the source code in plugins/render/skills/render-mcp/SKILL.md, these servers serve three critical functions:

• Capability description – Each tool (e.g., list_services, get_runtime_logs) publishes a JSON schema defining valid inputs and outputs, which the AI SDK consumes to generate valid API calls.
• Authentication management – The server handles OAuth/OIDC flows, token refresh, and scoped access, ensuring agents never process raw API keys.
• Contract stability – Tool schemas are versioned and can be pre-generated into static definitions using mcp-to-ai-sdk, guaranteeing that agents only invoke supported endpoints.

Official plugins across the repository implement this pattern. The Wix MCP server enables e-commerce and CMS extensions as referenced in plugins/wix/.codex-plugin/plugin.json, while the Vercel MCP server provides project-level data queries as documented in plugins/vercel/skills/vercel-api/SKILL.md.

Configuring MCP Servers via .mcp.json

Configuration for an MCP server resides in a .mcp.json file located at the root of the plugin repository. This file establishes the endpoint identity, authentication requirements, and tool catalog location.

As shown in plugins/openai-developers/.mcp.json, the configuration object requires four primary fields:

• name – Logical identifier used by skills (e.g., "render" or "vercel").
• url – Base URL of the MCP endpoint (e.g., https://mcp.render.com).
• auth – OAuth configuration object containing type, clientId, and required scopes.
• toolCatalog – Optional path to a JSON file generated by mcp-to-ai-sdk that lists all tool schemas.

A complete configuration example from the OpenAI Developers plugin looks like this:

{
  "name": "openai-docs",
  "url": "https://docs.openai.com/mcp",
  "auth": {
    "type": "oauth",
    "clientId": "<YOUR_CLIENT_ID>",
    "scopes": ["read", "search"]
  },
  "toolCatalog": "tools/catalog.json"
}

Integrating MCP Servers into Skills

Once the .mcp.json file exists, plugin skills reference the server by its logical name in their markdown documentation. This instructs the AI agent how to register the server in its tool configuration.

The Render MCP skill in plugins/render/skills/render-mcp/SKILL.md demonstrates this pattern:

## Quick setup

Add the Render MCP server to your AI tool's MCP config:

```yaml
mcp:
  render:
    url: https://mcp.render.com
    auth:
      type: oauth
      clientId: <YOUR_CLIENT_ID>

After registration, the AI SDK dynamically imports the tool catalog. The following example from [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) shows how to instantiate the client:

```javascript
import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  server: "render",          // matches the name in .mcp.json
  auth: { clientId: "..."}   // optional overrides
});

// Call a tool exactly as defined in the catalog
const services = await client.list_services();
console.log(services);

Generating Static Tool Catalogs and Fallback Patterns

To avoid runtime schema generation, plugins can pre-build tool catalogs using the mcp-to-ai-sdk CLI. This command generates a static JSON file that can be committed alongside the plugin:

npx mcp-to-ai-sdk --server render --output plugins/render/tools/catalog.json

Many skills implement a fallback strategy when MCP servers are unreachable. As documented in plugins/vercel/commands/_conventions.md, the pattern checks for MCP availability before falling back to CLI commands:

try {
  const services = await client.list_services();
  // Use MCP data
} catch (e) {
  // MCP not reachable → use the Render CLI
  const services = await execSync("render services list", { encoding: "utf8" });
}

This approach ensures resilience while maintaining the MCP server's rich schema definitions when available.

Summary

• MCP servers are HTTP endpoints that expose standardized tool definitions via the Model Context Protocol, allowing AI agents to discover and invoke platform APIs dynamically.
• Configuration occurs in .mcp.json at the plugin root, specifying the server name, base URL, OAuth parameters, and optional tool catalog path.
• Integration happens through skill markdown files that reference the server name, combined with the @ai-sdk/mcp client to create typed tool invocations.
• Static generation via mcp-to-ai-sdk creates commitable tool catalogs, while fallback logic ensures agents can degrade to CLI commands when the HTTP endpoint is unavailable.

Frequently Asked Questions

What does MCP stand for in Codex plugins?

MCP stands for Model Context Protocol. It is a standardized protocol that defines how AI agents discover and interact with external tools through HTTP endpoints exposing JSON schemas, authentication flows, and versioned capabilities.

Where is the MCP server configuration file located?

The MCP server configuration file is named .mcp.json and must reside at the root of the plugin repository. This file is parsed by the Codex plugin system to register the server with the AI agent's tool configuration.

How do AI agents authenticate with an MCP server?

Authentication is handled through OAuth 2.0/OIDC flows defined in the .mcp.json file's auth field. The server manages token acquisition, refresh cycles, and scoped access, so agents interact with the API through managed sessions rather than raw API keys.

Can MCP servers work offline or without the hosted endpoint?

While MCP servers require a reachable HTTP endpoint for full functionality, plugins can implement fallback logic that degrades to local CLI commands when the server is unavailable. This pattern is documented in plugins/vercel/commands/_conventions.md and ensures agents remain operational even during connectivity issues.

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