Lifecycle of an MCP Configuration in OpenAI Plugins: A Complete Technical Guide

The lifecycle of an MCP configuration in OpenAI plugins consists of six distinct stages—creation, editing, loading, runtime use, updating, and reloading—where configuration changes only take effect after a full Codex restart due to client-side caching.

The openai/plugins repository uses Model Context Protocol (MCP) configurations to connect Codex agents with external tool servers. An MCP configuration lifecycle governs how .mcp.json files are scaffolded, validated, and consumed by the plugin runtime, ensuring secure authentication and efficient tool discovery across the plugin ecosystem.

Stage 1: Scaffolding the Configuration File

New plugins optionally include an MCP placeholder during initialization. The plugin-creator agent supports a --with-mcp flag that generates an empty .mcp.json file in the plugin root directory.

Run the scaffolding command from the repository root:

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

In plugins/.agents/skills/plugin-creator/scripts/create_basic_plugin.py, this flag triggers logic that writes plugin_root / ".mcp.json" with an empty template. This file serves as the persistent store for MCP server endpoints throughout the plugin's lifecycle.

Stage 2: Defining MCP Server Endpoints

After scaffolding, developers populate .mcp.json with server definitions. A valid configuration contains an array of server objects specifying URLs and authentication schemes.

Example .mcp.json structure:

{
  "servers": [
    {
      "url": "https://mcp.my-service.com",
      "auth": {
        "type": "oauth",
        "scopes": ["read", "write"]
      }
    }
  ]
}

Each entry maps to an external MCP server that exposes tools via the Model Context Protocol. Plugins like Supabase, Vercel, and Wix in the openai/plugins repository maintain their own .mcp.json files following this schema.

Stage 3: Loading During Plugin Initialization

When Codex loads a plugin, it locates the MCP configuration through the mcpServers field in .codex-plugin/plugin.json. This field contains a relative path to the .mcp.json file.

Example plugin.json entry:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "mcpServers": "./.mcp.json"
}

The runtime reads this reference to instantiate an authenticated MCP client. This occurs once during plugin initialization, parsing the JSON to establish connections, perform OAuth flows, and cache discovered tools. The client remains resident in memory for the duration of the plugin session.

Stage 4: Runtime Tool Discovery and Execution

Skills and commands retrieve the cached MCP client via the createMCPClient helper to invoke remote tools. The runtime prefers MCP routes for read-only operations like listing projects or searching documentation.

Example TypeScript usage within a skill:

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

const client = await createMCPClient({ url: "https://mcp.my-service.com" });
const tools = await client.tools();   // Discover server-provided tools
// ... execute tools ...
await client.close();

As documented in plugins/vercel/skills/vercel-api/SKILL.md, write-heavy actions fall back to native SDKs or CLIs when the MCP server does not expose the required endpoint, creating a hybrid execution model.

Stage 5: Updating Configuration Values

When MCP endpoints, authentication tokens, or scopes change, developers edit the existing .mcp.json file directly. However, because the MCP client is instantiated and cached during Stage 3, configuration changes do not take effect immediately.

The source code in create_basic_plugin.py explicitly notes that cached clients persist until the plugin environment terminates. This design prevents connection churn but requires explicit action to refresh the configuration state.

Stage 6: Reloading After Configuration Changes

To apply updates, the developer must restart the Codex environment or reload the plugin. This forces the runtime to re-execute Stage 3, parsing the modified .mcp.json and instantiating a fresh MCP client with updated parameters.

Restart command:

codex restart

Documentation across multiple plugins—including Supabase and Daloopa—reinforces this requirement, stating that users must "restart Codex after updating the MCP configuration" to activate new server settings or refreshed authentication tokens.

Summary

• Creation: Use --with-mcp in create_basic_plugin.py to scaffold .mcp.json
• Editing: Define servers with URLs and OAuth scopes in .mcp.json
• Loading: The runtime reads the mcpServers path from .codex-plugin/plugin.json at startup
• Runtime: Skills call createMCPClient to discover and execute tools from cached connections
• Update: Editing .mcp.json alone does not refresh active connections
• Reload: A full Codex restart is required to re-parse configuration and instantiate updated MCP clients

Frequently Asked Questions

Where is the MCP configuration file located in an OpenAI plugin?

The MCP configuration resides at the plugin root as .mcp.json. The plugin's metadata in .codex-plugin/plugin.json references this location via the mcpServers field, typically set to "./.mcp.json".

How do I add MCP support to an existing plugin?

If the plugin was not created with the --with-mcp flag, manually create a .mcp.json file in the plugin root directory and add the "mcpServers": "./.mcp.json" entry to .codex-plugin/plugin.json. Then restart Codex to load the configuration.

Why do I need to restart Codex after editing .mcp.json?

The OpenAI plugins runtime caches the MCP client and its connection pool during the initial loading stage to optimize performance. Because this client is not reactive to filesystem changes, a restart is necessary to re-initialize the connection with updated endpoints or authentication tokens.

What is the difference between plugin.json and .mcp.json?

.codex-plugin/plugin.json contains plugin metadata and declares whether MCP is used via the mcpServers pointer. .mcp.json contains the actual content of the MCP configuration, including server URLs, authentication types, and scope definitions.

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