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

Configure MCP for OpenAI plugins by creating a .mcp.json file in the plugin root and referencing it via the mcpServers field in .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 Configuration File

The MCP definition lives in a .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:

{
  "$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 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:

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

As shown in 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 and locates the .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 files.

Code Examples

Minimal MCP Configuration

Create plugins/my-plugin/.mcp.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:

{
  "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:

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

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 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 files to indicate when agents should prefer MCP tools versus REST/CLI fallbacks.
• Validate schema compliance – Ensure your .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 at the plugin root with server URLs and OAuth clientId (never store secrets).
• Reference the file in .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 files.
• Test locally following patterns in plugins/vercel/skills/ai-sdk/SKILL.md before submitting to the repository.

Frequently Asked Questions

Where does the .mcp.json file belong in an OpenAI plugin?

The .mcp.json file must reside at the root of your plugin directory (e.g., plugins/my-plugin/.mcp.json). The plugin manifest at .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 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 file (e.g., 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 to verify OAuth flows and schema validation before submitting your plugin to the repository.

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