# Where Are MCP Configurations Stored for OpenAI Plugins?

> Find where OpenAI MCP configurations are stored. Learn about the .mcp.json file location within the openai/plugins repository and plugin.json reference.

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

---

**OpenAI plugins store Model Context Protocol (MCP) configurations in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file located at the root of each plugin directory, referenced by the `mcpServers` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This field contains a relative path pointing to the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file.

Example from the cloudflare plugin manifest located at [`plugins/cloudflare/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.codex-plugin/plugin.json):

```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`](https://github.com/openai/plugins/blob/main/.mcp.json) files.

## MCP Configuration Schema and Structure

### The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) Schema

The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) referenced by [`plugins/cloudflare/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.codex-plugin/plugin.json)
- **openai-developers**: [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json) referenced by [`plugins/openai-developers/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.codex-plugin/plugin.json)
- **build-ios-apps**: [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/build-ios-apps/.mcp.json) referenced by [`plugins/build-ios-apps/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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:

```javascript
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`](https://github.com/openai/plugins/blob/main/.mcp.json) files at the plugin root directory
- The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest references these settings via the `mcpServers` field using a relative path such as [`./.mcp.json`](https://github.com/openai/plugins/blob/main/./.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to determine the relative path to the configuration file, then loads the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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.