# 8 Common Pitfalls When Configuring MCP for OpenAI Plugins

> Avoid common pitfalls configuring MCP for OpenAI plugins. Learn to fix missing .mcp.json files, cache issues, incorrect OAuth, and endpoint misconfigurations for seamless integration.

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

---

**The most frequent failures when configuring MCP for OpenAI plugins stem from missing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) files, stale Codex caches, incorrect OAuth setup, and using read-only MCP endpoints for write operations without a REST fallback.**

Configuring MCP for OpenAI plugins enables agents to invoke structured tool calls through the Model Context Protocol, yet small missteps in the setup chain can silently break the entire integration. The `openai/plugins` repository demonstrates these failure modes across production plugins such as Cloudflare, Vercel, Wix, and Daloopa. Understanding the exact file paths and canonical patterns documented in the source code is the fastest way to avoid tool-discovery failures and runtime errors.

## What Is MCP in OpenAI Plugins?

MCP integration follows a three-layer architecture inside the `openai/plugins` codebase. First, the **MCP server definition** lives in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file at the plugin root. Second, the **plugin manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) links to that definition through the `mcpServers` field. Third, **skill code** reads the MCP definition, generates input and output tool schemas, and invokes the server at runtime. The Vercel skill in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) shows the canonical execution pattern: it attempts an MCP call first and falls back to the REST API when a tool is not covered by the MCP surface.

## Common MCP Configuration Pitfalls

### 1. Missing or Malformed [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)

The plugin root must contain a valid [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) that defines at least one entry under `mcpServers`. If this file is missing or malformed, the agent cannot locate any MCP server, and all subsequent tool calls fail. The Cloudflare plugin provides the canonical example in [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json), which specifies the server `type` and `url`, while [`plugins/daloopa/README.md`](https://github.com/openai/plugins/blob/main/plugins/daloopa/README.md) explicitly reminds developers to place the Daloopa MCP configuration in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) at the plugin root.

### 2. Forgetting to Restart Codex After MCP Changes

Codex caches the manifest at load time, so edits to [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) are invisible until the process restarts. The Daloopa setup skill in [`plugins/daloopa/skills/setup/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/daloopa/skills/setup/SKILL.md) notes that you must stop and restart Codex after any MCP change; otherwise the skill continues to invoke the old server map or fails with a "tool not found" error.

### 3. Using MCP Discovery When API References Already Exist

Invoking MCP for endpoints that already have explicit API references creates duplicate requests, adds latency, and can produce conflicting state. The Wix App skill checklist in [`plugins/wix/skills/wix-app/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/SKILL.md) instructs agents to check API references first and use MCP only for gaps, preventing redundant calls against both the Wix Headless API and the MCP server.

### 4. Calling MCP for Write-Only Operations

Many MCP servers expose read-only methods, so attempting a write through MCP returns an error instead of mutating state. The Vercel skill in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) documents this limitation explicitly and recommends using the native REST API for any write-only or unsupported operation.

### 5. Assuming the MCP Server Is Always Reachable

Network interruptions, OAuth failures, or server downtime can render the MCP surface unavailable at runtime. The Vercel skill solves this by implementing an MCP-first, CLI-fallback pattern in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md), ensuring the agent degrades gracefully to the REST API instead of hard-failing.

### 6. Incorrect Authentication or Expired OAuth Tokens

MCP servers often require an OAuth flow on first connection, and missing or expired tokens block every call. The Cloudflare [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) notes this requirement explicitly, yet developers frequently skip the initial auth handshake, leaving the skill unable to authenticate even when the rest of the configuration is correct.

### 7. Invoking MCP in Skills That Deliberately Avoid It

Not every skill in an MCP-enabled plugin uses the protocol; some UI-only or front-end steps intentionally bypass MCP to avoid "no tool found" errors. The Wix Headless skill in [`plugins/wix/skills/wix-headless/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/SKILL.md) explicitly states "No REST calls required. No MCP.", and accidentally calling MCP there breaks the execution flow.

### 8. Over-Reliance on Generic `search()` Without Scoping

The generic `search()` endpoint can return noisy or irrelevant results if called without a specific tool schema to narrow the scope. The Vercel skill documentation warns against this in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md), advising developers to use `search()` only for gaps and to rely on precise tool definitions for predictable output.

## Recommended Patterns from the Source Code

### Structure a Minimal [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)

Place this file at the plugin root and reference it from [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).

```json
{
  "mcpServers": {
    "<your-server-name>": {
      "type": "http",
      "url": "https://<your-mcp-host>/mcp",
      "note": "Optional description – e.g. OAuth on first connection"
    }
  }
}

```

The manifest link should look like the Cloudflare example in [`plugins/cloudflare/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.codex-plugin/plugin.json):

```json
{
  "name": "cloudflare",
  "mcpServers": "./.mcp.json"
}

```

### Load and Validate the Configuration

Skill code should read and validate the JSON before generating tool schemas. The following Node-style pseudocode mirrors the pattern used across the repository:

```javascript
import fs from "fs";
import path from "path";

export async function loadMCPConfig(pluginRoot) {
  const mcpPath = path.join(pluginRoot, ".mcp.json");
  const raw = await fs.promises.readFile(mcpPath, "utf8");
  const cfg = JSON.parse(raw);

  if (!cfg.mcpServers) {
    throw new Error("MCP servers missing");
  }

  return cfg.mcpServers;
}

```

### Implement MCP-First with REST Fallback

Derived from the Vercel skill in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md), this pattern tries the read-only MCP endpoint first and falls back to the native REST API when the tool is unavailable:

```javascript
import { createMCPClient } from "@ai-sdk/mcp";

async function getProjectInfo(projectId) {
  const mcp = await createMCPClient({ server: "vercel-api" });

  try {
    return await mcp.call("getProject", { projectId });
  } catch (e) {
    const resp = await fetch(
      `https://api.vercel.com/v9/projects/${projectId}`,
      {
        headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
      }
    );

    if (!resp.ok) throw new Error("REST call failed");
    return await resp.json();
  }
}

```

### Restart Codex After Configuration Changes

After editing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), reload the manifest by restarting the Codex process:

```bash
codex stop
codex start

```

The Daloopa setup skill in [`plugins/daloopa/skills/setup/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/daloopa/skills/setup/SKILL.md) emphasizes that this step is mandatory; otherwise Codex continues to use the cached manifest.

## Summary

- **Always place a valid [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** at the plugin root and reference it correctly from [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).
- **Restart Codex** after every change to [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) so the new manifest is loaded.
- **Prefer explicit API references** when they exist, and invoke MCP only to fill gaps.
- **Use a REST or CLI fallback** for write operations and when the MCP server is unreachable.
- **Verify OAuth flows** before first use, and avoid calling MCP in skills that are explicitly MCP-free.

## Frequently Asked Questions

### What file defines an MCP server in an OpenAI plugin?

The MCP server definition belongs in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file located at the plugin root. According to the `openai/plugins` source code, this file must contain a top-level `mcpServers` object that maps server names to their connection details, as shown in [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json).

### Why do MCP tool calls fail after editing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)?

Codex caches the plugin manifest at load time, so any changes to [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) are ignored until the process restarts. The Daloopa setup skill in [`plugins/daloopa/skills/setup/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/daloopa/skills/setup/SKILL.md) explicitly warns that you must run `codex stop` and `codex start` to pick up the updated configuration.

### Should skills always prefer MCP over REST APIs?

No. The Wix App skill in [`plugins/wix/skills/wix-app/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/SKILL.md) and the Vercel skill in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) both recommend checking explicit API references first. Use MCP only for gaps in coverage to avoid duplicate requests, latency, and conflicting state.

### How do I handle write operations in an MCP-enabled plugin?

Many MCP servers are read-only, so write operations should use the native REST API. The Vercel skill demonstrates an MCP-first, REST-fallback pattern in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) that catches MCP failures and degrades to an authenticated REST call for unsupported or write-only endpoints.