What Is .mcp.json Used for in OpenAI Plugins? A Complete Guide to MCP Configuration

.mcp.json is the Model‑Context‑Protocol (MCP) configuration file that defines how Codex plugins expose AI‑agent‑friendly tools, authentication, and transport endpoints.

In the openai/plugins repository, this JSON file lives alongside a plugin’s main manifest and bridges static metadata with dynamic tool‑calling capabilities. It allows agents to discover and invoke third‑party services without managing raw HTTP or CLI implementations.

Understanding the .mcp.json File Structure

The .mcp.json file contains a top‑level mcpServers object that maps server names to their connection details. According to the plugin specification in .agents/skills/plugin-creator/references/plugin-json-spec.md (line 65), this configuration describes one or more MCP servers that handle tool definitions and runtime communication.

The mcpServers Object

Each key inside mcpServers represents a distinct service endpoint. For example, in plugins/zoom/.mcp.json, the configuration defines a single Zoom MCP server with specific transport and authentication settings:

{
  "mcpServers": {
    "zoom": {
      "type": "http",
      "url": "https://mcp.zoom.us/mcp/meeting/streamable",
      "oauth": {
        "client_id": "<ZOOM_PUBLIC_CLIENT_ID>"
      }
    }
  }
}

Transport Types and Authentication

The type field determines how the agent communicates with the server. Common values include http and streamable. The optional oauth object enables authenticated calls to third‑party APIs, as seen in the Zoom example above. For simpler integrations, authentication can be omitted entirely, such as in plugins/stripe/.mcp.json:

{
  "mcpServers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com"
    }
  }
}

How .mcp.json Connects to plugin.json

The plugin manifest (plugin.json) references the MCP configuration through the mcpServers field, which contains a string path to the .mcp.json file. In plugins/zoom/.codex-plugin/plugin.json, this linkage appears as:

{
  "mcpServers": "./.mcp.json"
}

This relative path tells the Codex runtime where to find the MCP server definitions when loading the plugin. The evaluation code in plugin-eval/src/evaluators/plugin.js (line 135) extracts this path during plugin initialization using the snippet ["mcpServers", manifest.mcpServers].

Real‑World Examples from the Repository

The openai/plugins repository includes several production implementations demonstrating different .mcp.json patterns.

Zoom Integration with OAuth

The Zoom plugin (plugins/zoom/.mcp.json) demonstrates a complete OAuth‑enabled configuration. It specifies the streamable transport type for real‑time meeting data and includes a public client ID for OAuth flows.

Minimal HTTP Configuration

The Stripe plugin (plugins/stripe/.mcp.json) shows a minimal setup requiring only the transport type and endpoint URL. This pattern suits services that don’t require user authentication or use API keys managed elsewhere.

OpenAI Developers Plugin

The OpenAI Developers plugin includes test validation in openai-developers/tests/openai-platform-api-key.test.mjs (lines 153‑155). These tests assert that the manifest correctly points to ./.mcp.json and verify that the server configurations load properly with arguments like "openai-api-key-local-confirmation".

Creating Your Own .mcp.json Configuration

To implement MCP functionality in your plugin, create a .mcp.json file in your plugin’s root directory alongside your plugin.json manifest.

Step 1: Define your MCP servers with appropriate transport and authentication:

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

Step 2: Reference the file in your plugin.json:

{
  "name": "myservice",
  "version": "1.0.0",
  "description": "My Service integration",
  "mcpServers": "./.mcp.json",
  "skills": "./skills/"
}

Step 3: Access the tools in your agent code using an MCP client:

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 dedicated configuration file for Model‑Context‑Protocol servers in Codex plugins.
• It defines transport types (http, streamable), endpoint URLs, and OAuth credentials for third‑party integrations.
• The file is referenced from plugin.json via the mcpServers field, typically set to "./.mcp.json".
• The evaluator (plugin-eval/src/evaluators/plugin.js) reads this path during plugin loading to initialize MCP connections.
• Examples in the repository show both complex OAuth flows (Zoom) and simple HTTP endpoints (Stripe).

Frequently Asked Questions

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

plugin.json contains static metadata about your plugin—including its name, version, and the path to .mcp.json—while .mcp.json specifically configures the dynamic Model‑Context‑Protocol servers that enable AI agents to call external tools. The manifest tells the runtime where to find the MCP configuration, and .mcp.json tells the runtime how to talk to the services.

Is OAuth required in .mcp.json?

No, OAuth is optional. The Stripe example in plugins/stripe/.mcp.json demonstrates a minimal configuration with only type and url fields. However, for services requiring user authentication—like Zoom—you must include the oauth object with a client_id to enable secure, delegated access.

What transport types are supported in .mcp.json?

According to the repository examples, supported transport types include http and streamable. The http type is used for standard REST‑like endpoints, while streamable supports real‑time data flows, as implemented in the Zoom plugin for meeting streams.

How does the Codex runtime use .mcp.json during plugin evaluation?

During initialization, the runtime reads the mcpServers path from plugin.json, then parses .mcp.json to discover available tool endpoints. The evaluation code in plugin-eval/src/evaluators/plugin.js extracts this configuration to establish connections, allowing agents to invoke tools like list_drains or get_runtime_logs without managing raw network calls.

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