How to Update MCP Configurations for an Existing OpenAI Plugin

You update MCP configurations by editing the .mcp.json file in the plugin's root directory and reloading the Codex runtime to apply the changes.

The Model Context Protocol (MCP) enables OpenAI plugins to communicate with external services through a standardized configuration layer. In the openai/plugins repository, each MCP-enabled plugin stores its connection settings in a dedicated JSON file that the Codex runtime reads when executing skills. Updating these configurations allows you to change endpoints, rotate credentials, or adjust performance parameters without modifying the plugin's core logic.

Understanding MCP Configuration Files

MCP configurations rely on two key files: the plugin manifest that declares the configuration location, and the .mcp.json file that contains the actual server settings.

The Plugin Manifest (.codex-plugin/plugin.json)

The plugin manifest references the MCP configuration through the mcpServers field. According to the source code in the openai/plugins repository, this field typically points to a relative path such as "./.mcp.json".

In plugins/openai-developers/.codex-plugin/plugin.json, the manifest declares:

{
  "mcpServers": "./.mcp.json"
}

This tells the Codex runtime where to locate the server definitions when the plugin initializes.

The MCP Configuration File (.mcp.json)

The .mcp.json file resides at the root of the plugin directory (e.g., plugins/openai-developers/.mcp.json or plugins/cloudflare/.mcp.json) and contains the server connection details. The structure includes:

• servers: An array of server objects with url and auth configuration
• auth: Authentication details including type (oauth, apiKey, or bearer) and corresponding credentials
• options: Runtime parameters such as timeoutMs and retry counts

A typical configuration looks like this:

{
  "servers": [
    {
      "url": "https://<service>.mcp.example.com",
      "auth": {
        "type": "oauth",
        "clientId": "<YOUR_CLIENT_ID>",
        "scopes": ["read", "write"]
      }
    }
  ],
  "options": {
    "timeoutMs": 60000,
    "retry": 3
  }
}

Step-by-Step Guide to Update MCP Configurations

Follow these steps to modify the MCP configuration for any existing plugin in the repository.

1. Locate the Plugin Directory

Navigate to the plugin's root folder within the repository. For example:

cd plugins/openai-developers/

Other examples include plugins/cloudflare/ and plugins/build-ios-apps/, each containing their own .mcp.json file.

2. Edit the .mcp.json File

Open the configuration file in your text editor. Update the relevant fields based on your requirements:

• Change the endpoint: Modify the url field in the servers array
• Update authentication: Change the auth.type to oauth, apiKey, or bearer, and supply new credentials such as clientId or apiKey
• Adjust timeouts: Modify options.timeoutMs or options.retry values

Example configuration update:

{
  "servers": [
    {
      "url": "https://new-mcp.example.com",
      "auth": {
        "type": "apiKey",
        "apiKey": "sk_live_XXXXXXXXXXXXXXXX"
      }
    }
  ],
  "options": {
    "timeoutMs": 120000,
    "retry": 5
  }
}

3. Save the Configuration

Write the changes to disk. Ensure the file remains valid JSON with no trailing commas or syntax errors.

4. Reload the Plugin

The Codex runtime must reload to recognize configuration changes. You have two options:

Option A: Restart the Codex development server

pkill -f codex
npm start

Option B: Regenerate using the plugin creator script

Run the helper script with the --with-mcp flag to refresh the configuration structure:

python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  --name openai-developers \
  --with-mcp

The create_basic_plugin.py script regenerates the .mcp.json placeholder while preserving your plugin structure.

Regenerating MCP Configurations with the Plugin Creator

The repository includes a utility script for scaffolding and updating plugin configurations. Located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py, this helper can generate a fresh .mcp.json skeleton when you need to reset or reinitialize the configuration.

To regenerate the MCP configuration:

python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  --name my-plugin \
  --with-mcp

This approach is useful when you want to ensure the JSON schema matches the latest specification documented in .agents/skills/plugin-creator/references/plugin-json-spec.md.

Verifying Your MCP Configuration Changes

After updating and reloading, verify that the plugin connects to the new MCP server:

1. Invoke any skill that uses an MCP-enabled tool
2. Check the skill's execution logs to confirm requests route to the updated endpoint
3. Verify authentication succeeds with the new credentials

If the plugin manifest references the configuration using a relative path like "./.mcp.json", no additional changes are required to the .codex-plugin/plugin.json file.

Summary

• MCP configurations for OpenAI plugins reside in .mcp.json files at the plugin root (e.g., plugins/openai-developers/.mcp.json)
• The plugin manifest (.codex-plugin/plugin.json) declares the configuration location via the mcpServers field
• Update server URLs, authentication credentials (clientId, apiKey), and runtime options (timeoutMs, retry) directly in the JSON file
• Reload the Codex runtime by restarting the server or using the create_basic_plugin.py script with --with-mcp
• Supported authentication types include oauth, apiKey, and bearer

Frequently Asked Questions

Where is the MCP configuration stored for OpenAI plugins?

The MCP configuration is stored in a file named .mcp.json located at the root of each plugin directory (e.g., plugins/openai-developers/.mcp.json). The plugin manifest (.codex-plugin/plugin.json) references this file through the mcpServers field, typically using the relative path "./.mcp.json" as implemented in the openai/plugins repository.

What authentication types are supported in .mcp.json?

The .mcp.json file supports three authentication types in the auth.type field: oauth for OAuth 2.0 flows (requiring clientId and scopes), apiKey for static API key authentication (requiring an apiKey value), and bearer for bearer token authentication. Each type requires corresponding credential fields within the auth object to properly authenticate with the MCP server.

How do I reload an OpenAI plugin after updating MCP settings?

You must reload the Codex runtime to apply MCP configuration changes. Either restart the Codex development server using pkill -f codex followed by your start command, or run the plugin creator script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py with the --with-mcp flag to regenerate the configuration and trigger a reload.

Can I have multiple MCP servers in one plugin?

Yes. The servers field in .mcp.json is an array, allowing you to define multiple MCP server endpoints within a single configuration file. Each server object can specify its own url, auth method, and optional parameters, enabling the plugin to communicate with multiple external services through the Model Context Protocol.

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