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

> Understand the full lifecycle of an MCP configuration in OpenAI plugins. Learn about creation, editing, loading, runtime, updating, and reloading for effective plugin management.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-06-06

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file in the plugin root directory.

Run the scaffolding command from the repository root:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) with server definitions. A valid configuration contains an array of server objects specifying URLs and authentication schemes.

Example [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) structure:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This field contains a relative path to the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file.

Example [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) entry:

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

```typescript
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) and instantiating a fresh MCP client with updated parameters.

Restart command:

```bash
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`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) to scaffold [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)
- **Editing**: Define servers with URLs and OAuth scopes in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)
- **Loading**: The runtime reads the `mcpServers` path from [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) at startup
- **Runtime**: Skills call `createMCPClient` to discover and execute tools from cached connections
- **Update**: Editing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json). The plugin's metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file in the plugin root directory and add the `"mcpServers": "./.mcp.json"` entry to [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). Then restart Codex to load the configuration.

### Why do I need to restart Codex after editing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)?

[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) contains plugin metadata and declares *whether* MCP is used via the `mcpServers` pointer. [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) contains the actual *content* of the MCP configuration, including server URLs, authentication types, and scope definitions.