Where Are MCP Configurations Stored for OpenAI Plugins?

OpenAI plugins store Model Context Protocol (MCP) configurations in a .mcp.json file located at the root of each plugin directory, referenced by the mcpServers field in .codex-plugin/plugin.json.

In the openai/plugins repository, understanding where MCP configurations are stored is critical for developers integrating Model Context Protocol capabilities. Each plugin maintains its MCP settings in a standardized location that the Codex runtime automatically discovers during initialization.

Default MCP Configuration File Location

According to the source code in the openai/plugins repository, MCP configurations reside in a JSON file named .mcp.json placed at the top-level directory of each plugin. This convention ensures that the Codex runtime can automatically discover server settings when loading the plugin.

The file must sit adjacent to the .codex-plugin directory rather than inside it. For example, in the cloudflare plugin, the configuration lives at plugins/cloudflare/.mcp.json, not within the plugin manifest folder itself.

How the Plugin Manifest References MCP Settings

The connection between the plugin and its MCP configuration is established through the mcpServers field in .codex-plugin/plugin.json. This field contains a relative path pointing to the .mcp.json file.

Example from the cloudflare plugin manifest located at plugins/cloudflare/.codex-plugin/plugin.json:

{
  "name": "cloudflare",
  "description": "Manage Cloudflare services",
  "mcpServers": "./.mcp.json"
}

This pattern appears consistently throughout the repository, with the openai-developers and build-ios-apps plugins implementing identical references to their respective .mcp.json files.

MCP Configuration Schema and Structure

The .mcp.json Schema

The .mcp.json file follows a structured schema that defines server endpoints and authentication mechanisms. The configuration supports multiple servers and various authentication types through a standardized JSON format.

Minimal configuration template:

{
  "version": "1.0",
  "servers": [
    {
      "url": "https://example.mcp.com",
      "auth": {
        "type": "oauth",
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>"
      }
    }
  ]
}

Real-World Configuration Examples

The repository contains working implementations that demonstrate this structure:

• cloudflare: plugins/cloudflare/.mcp.json referenced by plugins/cloudflare/.codex-plugin/plugin.json
• openai-developers: plugins/openai-developers/.mcp.json referenced by plugins/openai-developers/.codex-plugin/plugin.json
• build-ios-apps: plugins/build-ios-apps/.mcp.json referenced by plugins/build-ios-apps/.codex-plugin/plugin.json

These files contain the authoritative MCP server URLs, authentication details, and connection settings for each plugin.

Accessing MCP Configuration Programmatically

When developing skills that need to read MCP settings, reference the file relative to the plugin root:

import fs from 'fs';
import path from 'path';

// Resolve the .mcp.json relative to the plugin root
const mcpPath = path.resolve(__dirname, '..', '.mcp.json');
const mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));

console.log('MCP server URL:', mcpConfig.servers[0].url);

This approach ensures your code remains compatible with the standardized file locations used throughout the openai/plugins ecosystem.

Summary

• MCP configurations for OpenAI plugins are stored in .mcp.json files at the plugin root directory
• The .codex-plugin/plugin.json manifest references these settings via the mcpServers field using a relative path such as ./.mcp.json
• Configuration files include server URLs, authentication details, and version information in a structured JSON schema
• Real implementations exist in the cloudflare, openai-developers, and build-ios-apps plugins within the openai/plugins repository

Frequently Asked Questions

Can I store MCP configurations in a different file name or location?

The Codex runtime specifically looks for the path defined in the mcpServers field of your plugin manifest. While you technically could use a different filename by updating this reference, the .mcp.json convention at the root directory is the standardized approach used across the openai/plugins repository. Deviating from this pattern may cause compatibility issues with automated tooling.

What authentication types are supported in .mcp.json?

The configuration schema supports various authentication methods including OAuth, as indicated by the auth.type field. The specific implementation details depend on the MCP server requirements, with common fields including clientId and clientSecret for OAuth-based connections. Check the specific server documentation for supported authentication schemes.

Does every OpenAI plugin require an .mcp.json file?

No, only plugins that implement Model Context Protocol (MCP) capabilities require this configuration file. Plugins that do not connect to MCP servers omit the mcpServers field from their manifest entirely. The presence of this field indicates that the plugin relies on external MCP services.

How does the Codex runtime locate the MCP configuration?

The runtime reads the mcpServers value from .codex-plugin/plugin.json to determine the relative path to the configuration file, then loads the .mcp.json file from the plugin's root directory to obtain connection parameters. This discovery happens automatically when the plugin is loaded, requiring no manual path resolution by the end user.

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