# How to Configure MCP for OpenAI Plugins: A Complete Developer Guide

> Configure MCP for OpenAI plugins by creating an mcp.json file and referencing it in plugin.json. Enable structured tool-calling and automatic OAuth handling for AI agents.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Configure MCP for OpenAI plugins by creating a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file in the plugin root and referencing it via the `mcpServers` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), enabling structured tool-calling and automatic OAuth handling for AI agents.**

OpenAI plugins in the `openai/plugins` repository are packaged as Codex plugins that optionally expose Model Context Protocol (MCP) servers. This configuration allows AI agents to invoke your plugin's functionality through standardized, schema-validated tools rather than direct API calls. Setting up MCP requires placing a specific configuration file in your plugin directory and linking it through the plugin manifest.

## What Is MCP in OpenAI Plugins?

The **Model Context Protocol (MCP)** defines a structured interface between AI agents and external tools. When you configure MCP for an OpenAI plugin, you expose capabilities through explicitly typed `inputSchema` and `outputSchema` definitions that prevent hallucination.

According to the `openai/plugins` source code, MCP configuration enables three key capabilities:

- **Structured I/O** – Tool parameters and returns are validated against JSON schemas.
- **Automatic Authentication** – The MCP client (`@ai-sdk/mcp`) handles OAuth flows and token refresh.
- **Runtime Discovery** – Agents dynamically load tool definitions from the MCP server catalog.

## The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) Configuration File

The MCP definition lives in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file placed at the root of your plugin repository. This file follows the MCP specification (`spec.modelcontextprotocol.io`) and defines server endpoints and authentication.

### File Structure

Create `plugins/<your-plugin>/.mcp.json` with the following structure:

```json
{
  "$schema": "https://spec.modelcontextprotocol.io/mcp-schema.json",
  "servers": [
    {
      "url": "https://my-plugin.mcp.com",
      "auth": {
        "type": "oauth",
        "clientId": "YOUR_CLIENT_ID"
      },
      "description": "MCP server for the custom plugin"
    }
  ]
}

```

**Critical security note:** Never store secrets, API keys, or passwords in this file. Only public identifiers like `clientId` belong here; the runtime securely retrieves tokens during execution.

### Key Fields

- **`url`** – Base URL of the MCP server endpoint.
- **`auth.type`** – Typically set to `oauth`; triggers automatic authorization flow on first use.
- **`clientId`** – Public identifier obtained from your provider's developer console.

Reference the example in [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json) for a concrete implementation.

## Linking MCP to the Plugin Manifest

The plugin manifest must explicitly reference the MCP configuration so the Codex runtime can discover and load it.

Update `plugins/<name>/.codex-plugin/plugin.json` to include the `mcpServers` field:

```json
{
  "name": "vercel",
  "version": "1.0.0",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

```

As shown in [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json), the path is relative to the plugin root.

## Implementation Architecture

The MCP integration follows a specific loading and execution flow:

1. **Manifest Parsing** – Codex reads [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and locates the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) reference.
2. **Server Registration** – The runtime registers tools defined by the MCP server (e.g., `list_projects`, `get_runtime_logs`).
3. **Skill Invocation** – Skills import tool definitions using patterns like `⤳ skill: vercel-api`.
4. **Transport Handling** – The MCP client manages OAuth, request formatting, and streaming transport.
5. **Fallback Execution** – When MCP lacks a specific tool, the skill falls back to REST or CLI calls as documented in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files.

## Code Examples

### Minimal MCP Configuration

Create [`plugins/my-plugin/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.mcp.json):

```json
{
  "$schema": "https://spec.modelcontextprotocol.io/mcp-schema.json",
  "servers": [
    {
      "url": "https://example.mcp.com",
      "auth": {
        "type": "oauth",
        "clientId": "my-client-id"
      }
    }
  ]
}

```

### Updating the Plugin Manifest

Modify [`plugins/my-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.codex-plugin/plugin.json):

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My custom OpenAI plugin",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

```

### Calling MCP Tools in Skills

Use the `@ai-sdk/mcp` client in your skill implementation:

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

async function listProjects() {
  const client = await createMCPClient({
    serverUrl: "https://example.mcp.com"
  });

  const result = await client.callTool("list_projects", {
    maxResults: 10
  });

  console.log("Projects:", result.projects);
}

```

The `serverUrl` matches the value defined in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), and tool names correspond to the MCP server's exposed capabilities.

### Handling Fallbacks to REST

When the MCP server lacks a specific operation, implement a REST fallback as shown in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md):

```javascript
import fetch from "node-fetch";

async function listProjectsFallback() {
  const resp = await fetch(
    "https://api.vercel.com/v9/projects?limit=10",
    { headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` } }
  );
  const data = await resp.json();
  console.log("Projects (REST fallback):", data.projects);
}

```

## Configuration Best Practices

- **Place [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) at the plugin root** – The Codex runtime expects this file in the top-level directory, not nested within skill folders.
- **Document MCP-first vs. fallback patterns** – Update your [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files to indicate when agents should prefer MCP tools versus REST/CLI fallbacks.
- **Validate schema compliance** – Ensure your [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) validates against the official MCP schema URL to prevent runtime parsing errors.
- **Test with `@ai-sdk/mcp`** – Verify tool calls locally before publishing, using the AI SDK to simulate agent interactions.

## Summary

- **Create [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** at the plugin root with server URLs and OAuth `clientId` (never store secrets).
- **Reference the file** in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) using the `"mcpServers": "./.mcp.json"` field.
- **Implement tool calls** using `createMCPClient` from `@ai-sdk/mcp` for automatic authentication and structured I/O.
- **Provide REST fallbacks** for operations not covered by your MCP server, documented in skill [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files.
- **Test locally** following patterns in [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) before submitting to the repository.

## Frequently Asked Questions

### Where does the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file belong in an OpenAI plugin?

The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file must reside at the root of your plugin directory (e.g., [`plugins/my-plugin/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.mcp.json)). The plugin manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) references this location via a relative path in the `mcpServers` field.

### What authentication method should I use for MCP servers?

Use `oauth` as the `auth.type` in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) and provide only the `clientId`. The MCP client library (`@ai-sdk/mcp`) automatically handles the OAuth flow, token storage, and refresh cycles. Never include API keys or client secrets in the JSON configuration.

### How do I handle operations not supported by the MCP server?

Document fallback strategies in your skill's [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file (e.g., [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md)). Implement alternative REST API calls or CLI commands directly in the skill code when the MCP server lacks specific tool definitions.

### Can I test MCP integration locally before publishing?

Yes. Use the `@ai-sdk/mcp` package to create a client instance pointing to your local or development MCP server URL. Test tool invocations using the methods shown in [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) to verify OAuth flows and schema validation before submitting your plugin to the repository.