# How to Update MCP Configurations for an Existing OpenAI Plugin

> Learn how to update MCP configurations for your existing OpenAI plugin by editing the .mcp.json file and reloading the Codex runtime. Apply changes effortlessly.

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

---

**You update MCP configurations by editing the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.codex-plugin/plugin.json), the manifest declares:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.mcp.json) file resides at the root of the plugin directory (e.g., [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json) or [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/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:

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

```bash
cd plugins/openai-developers/

```

Other examples include `plugins/cloudflare/` and `plugins/build-ios-apps/`, each containing their own [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

```json
{
  "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**

```bash
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:

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

```

The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script regenerates the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), this helper can generate a fresh [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) skeleton when you need to reset or reinitialize the configuration.

To regenerate the MCP configuration:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file.

## Summary

- **MCP configurations** for OpenAI plugins reside in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) files at the plugin root (e.g., [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json))
- The **plugin manifest** ([`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) located at the root of each plugin directory (e.g., [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json)). The plugin manifest ([`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.