# What Is the .mcp.json File in a Plugin? > Understand the .mcp.json file's purpose: defining AI-agent server endpoints, protocols, and authentication for plugin integrations. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: deep-dive - Published: 2026-09-12 --- **The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file is the Model-Context-Protocol (MCP) configuration file that defines AI-agent-facing server endpoints, transport protocols, and authentication credentials for plugin integrations.** The `openai/plugins` repository implements a Codex plugin architecture where [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) bridges static plugin metadata with dynamic tool-calling capabilities. This configuration file tells the Codex runtime how to connect to external services via the Model-Context-Protocol, enabling agents to discover and invoke tools without managing raw HTTP implementations. ## Core Purpose of the .mcp.json Configuration The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file declaratively specifies **MCP servers** that expose tool definitions to AI agents. According to the source code in [`plugins/zoom/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.mcp.json), this file contains the endpoint URLs, transport types, and OAuth parameters required for the Codex runtime to establish connections with third-party services like Zoom, Stripe, or custom APIs. When a plugin loads, the runtime reads this configuration to: - Discover available **tool-calling endpoints** (e.g., `list_drains`, `get_runtime_logs`) - Manage **OAuth-authenticated requests** through standardized credential handling - Select appropriate **transport mechanisms** (`http`, `streamable`, etc.) for agent-server communication ## Schema and Required Fields ### The mcpServers Object At the root level, [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) contains a single required key: `mcpServers`. This object maps server identifiers to their connection parameters. For example, in [`plugins/stripe/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/stripe/.mcp.json), the configuration defines a minimal HTTP server: ```json { "mcpServers": { "stripe": { "type": "http", "url": "https://mcp.stripe.com" } } } ``` ### Transport Configuration Each server entry requires a `type` field specifying the transport protocol. The Zoom plugin in [`plugins/zoom/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.mcp.json) demonstrates an HTTP transport with a streamable endpoint: ```json { "mcpServers": { "zoom": { "type": "http", "url": "https://mcp.zoom.us/mcp/meeting/streamable" } } } ``` Available transport types include `http` and `streamable`, determining whether the agent communicates via standard HTTP requests or persistent streaming connections. ### OAuth Authentication For services requiring user authentication, the configuration includes an `oauth` object containing the client identifier. The Zoom implementation shows this pattern: ```json { "oauth": { "client_id": "" } } ``` This allows the Codex runtime to initiate OAuth flows without hardcoding sensitive credentials in the main plugin logic. ## Linking .mcp.json to the Plugin Manifest The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file never exists in isolation. The main plugin manifest—located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or similar—references the MCP configuration through the `mcpServers` field (a string path). As 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) at line 65, this field accepts a relative path string. Example from [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json): ```json { "name": "zoom", "version": "1.0.0", "mcpServers": "./.mcp.json", "skills": "./skills/" } ``` This indirection allows plugin developers to separate connection credentials and endpoint configurations from the core plugin metadata. ## Runtime Loading and Evaluation During plugin initialization, the Codex runtime extracts the MCP configuration path from the manifest. In [`plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugin-eval/src/evaluators/plugin.js) at line 135, the evaluation code retrieves this value using the expression `["mcpServers", manifest.mcpServers]`. Test suites confirm this behavior in `openai-developers/tests/openai-platform-api-key.test.mjs` (lines 153-155), where assertions verify that `pluginManifest.mcpServers` correctly points to `"./.mcp.json"` and that the referenced file's contents populate the server arguments. ## Implementation Example To implement a custom MCP server configuration, create [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) in your plugin root: ```json { "mcpServers": { "myservice": { "type": "http", "url": "https://mcp.myservice.com", "oauth": { "client_id": "" } } } } ``` Then reference it in your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json): ```json { "name": "myservice", "version": "1.0.0", "description": "My Service integration", "mcpServers": "./.mcp.json", "skills": "./skills/" } ``` Agents can then consume these tools using the MCP client SDK: ```javascript import { createMCPClient } from '@ai-sdk/mcp'; const client = createMCPClient({ name: 'myservice', transport: { type: 'http' }, url: 'https://mcp.myservice.com', oauth: { clientId: process.env.MY_SERVICE_CLIENT_ID } }); const tools = await client.tools(); ``` ## Summary - **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** is the Model-Context-Protocol configuration file for OpenAI Codex plugins, residing alongside [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). - The file defines one or more **MCP servers** under the `mcpServers` key, specifying transport types (`http`, `streamable`), endpoint URLs, and OAuth credentials. - Plugin manifests reference this file via the **`mcpServers`** string field, enabling the Codex runtime to locate and load connection parameters as implemented in [`plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugin-eval/src/evaluators/plugin.js). - During initialization, the runtime evaluates this configuration to enable **tool discovery** and **authenticated API calls** for AI agents. ## Frequently Asked Questions ### What does MCP stand for in .mcp.json? MCP stands for **Model-Context-Protocol**, a standardized protocol that allows AI agents to discover and invoke external tools through structured endpoints rather than raw HTTP calls. The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file implements this protocol for the OpenAI Codex plugin architecture, bridging the plugin's static metadata with dynamic agent capabilities. ### How do I reference .mcp.json from my plugin manifest? Add the **`mcpServers`** field to your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file with a relative path string value, such as `"./.mcp.json"`. This field is 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) and is required for the runtime to locate your MCP configuration during the loading process. ### Can I define multiple MCP servers in a single .mcp.json file? Yes. The `mcpServers` object accepts multiple keys, where each key represents a distinct server connection. For example, you could define separate entries for `"stripe"` and `"zoom"` within the same file, each with independent URLs, transport types, and authentication parameters. ### What transport types does .mcp.json support? According to the source implementations in [`plugins/zoom/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.mcp.json) and [`plugins/stripe/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/stripe/.mcp.json), the configuration supports transport types including **`http`** and **`streamable`**. The transport type determines whether the agent communicates via standard HTTP requests or persistent streaming connections to the MCP server.