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

> Understand the .mcp.json file, the Model‑Context‑Protocol configuration for OpenAI plugins. Learn how it defines AI agent tools, authentication, and endpoints.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-11

---

**.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/zoom/.mcp.json), the configuration defines a single Zoom MCP server with specific transport and authentication settings:

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

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

```

## How .mcp.json Connects to plugin.json

The plugin manifest ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)) references the MCP configuration through the `mcpServers` field, which contains a string path to the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file. In [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json), this linkage appears as:

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

### Zoom Integration with OAuth

The Zoom plugin ([`plugins/zoom/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/./.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file in your plugin’s root directory alongside your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest.

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

```json
{
  "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`](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/"
}

```

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

```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 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`](https://github.com/openai/plugins/blob/main/plugin.json)** via the `mcpServers` field, typically set to `"./.mcp.json"`.
- The **evaluator** ([`plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) contains static metadata about your plugin—including its name, version, and the path to [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)—while [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json), then parses [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) to discover available tool endpoints. The evaluation code in [`plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/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.