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

> Discover what MCP servers in Codex plugins are. Learn how these standardized HTTP endpoints enable AI agents to securely discover and invoke platform capabilities using JSON schema definitions.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: tooling
- Published: 2026-06-29

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md).

## Configuring MCP Servers via .mcp.json

Configuration for an MCP server resides in a **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/render/skills/render-mcp/SKILL.md) demonstrates this pattern:

```markdown

## 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:

```bash
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`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/_conventions.md), the pattern checks for MCP availability before falling back to CLI commands:

```javascript
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/_conventions.md) and ensures agents remain operational even during connectivity issues.