What Is the .mcp.json File in a Plugin?

The .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 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 file declaratively specifies MCP servers that expose tool definitions to AI agents. According to the source code in 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 contains a single required key: mcpServers. This object maps server identifiers to their connection parameters. For example, in plugins/stripe/.mcp.json, the configuration defines a minimal HTTP server:

{
  "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 demonstrates an HTTP transport with a streamable endpoint:

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

{
  "oauth": {
    "client_id": "<ZOOM_PUBLIC_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 file never exists in isolation. The main plugin manifest—located at .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 at line 65, this field accepts a relative path string.

Example from plugins/zoom/.codex-plugin/plugin.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 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 in your plugin root:

{
  "mcpServers": {
    "myservice": {
      "type": "http",
      "url": "https://mcp.myservice.com",
      "oauth": {
        "client_id": "<MYSERVICE_PUBLIC_CLIENT_ID>"
      }
    }
  }
}

Then reference it in your plugin.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:

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 is the Model-Context-Protocol configuration file for OpenAI Codex plugins, residing alongside 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.
• 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 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 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 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 and 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.

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