8 Common Pitfalls When Configuring MCP for OpenAI Plugins

The most frequent failures when configuring MCP for OpenAI plugins stem from missing .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 file at the plugin root. Second, the plugin manifest at .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 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

The plugin root must contain a valid .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, which specifies the server type and url, while plugins/daloopa/README.md explicitly reminds developers to place the Daloopa MCP configuration in .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 are invisible until the process restarts. The Daloopa setup skill in 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 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 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, 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 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 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, 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

Place this file at the plugin root and reference it from .codex-plugin/plugin.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:

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

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, this pattern tries the read-only MCP endpoint first and falls back to the native REST API when the tool is unavailable:

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, reload the manifest by restarting the Codex process:

codex stop
codex start

The Daloopa setup skill in 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 at the plugin root and reference it correctly from .codex-plugin/plugin.json.
• Restart Codex after every change to .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 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.

Why do MCP tool calls fail after editing .mcp.json?

Codex caches the plugin manifest at load time, so any changes to .mcp.json are ignored until the process restarts. The Daloopa setup skill in 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 and the Vercel skill in 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 that catches MCP failures and degrades to an authenticated REST call for unsupported or write-only endpoints.

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