Troubleshooting MCP Configuration Errors in OpenAI Plugins: A Complete Guide

Most MCP configuration errors in OpenAI plugins stem from missing .mcp.json files, malformed JSON syntax, unreachable server endpoints, or stale authentication tokens that require reloading the plugin.

OpenAI plugins rely on the Model Context Protocol (MCP) to provide structured tool access for AI agents. Each plugin requires a .mcp.json configuration file that instructs the runtime—such as Codex—how to launch or connect to MCP servers. Misconfigurations in this file prevent tool discovery and cause runtime failures across the openai/plugins repository.

Understanding MCP Configuration Structure

The openai/plugins repository follows a uniform pattern for MCP setup. Every plugin that exposes tools via MCP must include a .mcp.json file at its root, adjacent to the .codex-plugin/plugin.json manifest.

The .mcp.json File Location and Format

Codex scans for .mcp.json as a sibling to the plugin manifest. The file contains a top-level mcpServers object that maps server names to their launch configurations.

In plugins/openai-developers/.mcp.json, the configuration defines a local Node.js server:

{
  "mcpServers": {
    "my-plugin-local": {
      "cwd": ".",
      "command": "node",
      "args": [
        "./mcp/server.mjs"
      ]
    }
  }
}

Contrast this with plugins/cloudflare/.mcp.json, which points to a remote HTTP endpoint:

{
  "mcpServers": {
    "cloudflare-api": {
      "type": "http",
      "url": "https://mcp.cloudflare.com/mcp",
      "note": "Official Cloudflare API MCP server. Uses OAuth on first connection."
    }
  }
}

Local vs. Remote Server Definitions

Local command-based servers require cwd, command, and args fields. The runtime executes this command in a subprocess and communicates via stdio. Remote HTTP servers require type: "http" and a valid url. These initiate persistent connections and typically require OAuth authentication on first use.

Common MCP Configuration Errors and Solutions

Configuration errors manifest as clear runtime exceptions. Below are the four primary failure modes and their remedies.

Missing or Malformed .mcp.json Files

The runtime throws Error: .mcp.json not found when the file is absent or misnamed. Validate the file exists in plugins/<plugin-name>/ and ensure the filename starts with a dot.

JSON syntax errors—trailing commas, missing braces, or invalid escaping—trigger parse errors. Validate the file using a JSON linter. A minimal valid configuration requires only the mcpServers wrapper and one server definition.

Broken Command Paths and Server URLs

When the command field references a missing binary or the url points to an unreachable endpoint, Codex cannot establish the MCP session. Test local commands manually from the plugin root:

node ./mcp/server.mjs

For remote servers, verify reachability with curl:

curl -s -X POST https://mcp.cloudflare.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"search","params":{"query":"dns"} }'

A successful response contains a result envelope. HTTP 401 or connection timeouts indicate network or authentication issues, not configuration syntax errors.

Authentication and OAuth Failures

Remote HTTP MCP servers initiate OAuth flows during first contact. Token exchange failures result in 401 Unauthorized errors. According to the Moody’s MCP skill in plugins/moody-s/skills/moody-s-explore-mcp/SKILL.md, you must complete the OAuth flow in the Codex interface before tools become available.

If authentication expires, the runtime cannot refresh tools. The remedy is to trigger re-authentication by reloading the plugin, which clears cached tokens and restarts the OAuth handshake.

Stale Plugin State and Caching Issues

After editing .mcp.json, Codex may continue using cached tool definitions. This causes "Tool name unknown" errors when calling newly added functions. As documented in plugins/daloopa/skills/setup/SKILL.md, you must reload the plugin to flush the cache:

codex plugin unload daloopa
codex plugin load daloopa

Alternatively, restart the Codex process entirely to force a fresh scan of .mcp.json.

Step-by-Step Diagnostic Workflow

The troubleshooting methodology in plugins/moody-s/skills/moody-s-explore-mcp/SKILL.md provides a repeatable blueprint for resolving MCP errors across all plugins:

1. Verify MCP Availability – Confirm the plugin loads without errors and tools appear in the session context.
2. Discover Tools – List live MCP tool schemas. Missing tools indicate an unreadable .mcp.json or failed server launch.
3. Smoke-test a simple read-only call – Execute a basic operation like findEntity to validate connectivity and schema alignment.
4. Summarize and remediate – If the smoke test fails, check file paths, JSON validity, and authentication state, then reinstall the plugin.

This workflow applies universally, whether debugging the Vercel CLI integration in plugins/vercel/skills/vercel-cli/SKILL.md or custom internal tools.

Summary

• Configuration errors trace back to the .mcp.json file, which must reside at the plugin root and contain valid JSON defining mcpServers.
• Local servers require valid command and cwd paths; remote servers require reachable HTTPS URLs and successful OAuth completion.
• Authentication failures (401 errors) require re-running the OAuth flow, often by reloading the plugin.
• Stale definitions persist until you run codex plugin reload or restart the runtime after any .mcp.json modification.

Frequently Asked Questions

What does "Error: .mcp.json not found" mean?

This error indicates the runtime cannot locate the MCP configuration file in the plugin directory. Ensure the file exists at plugins/<name>/.mcp.json (note the leading dot) and that it is not excluded by .gitignore or missing from the deployment artifact. Copy the structure from plugins/openai-developers/.mcp.json as a template.

How do I fix OAuth authentication errors in MCP plugins?

OAuth errors occur when the token exchange fails or expires. According to the Moody’s MCP documentation, you must complete the authentication flow in the Codex UI when first connecting to remote servers like Cloudflare. If you encounter 401 errors, unload and reload the plugin using codex plugin unload <name> followed by codex plugin load <name> to trigger a fresh authentication handshake.

Why does my MCP tool show as "unknown" after editing configuration?

Codex caches MCP tool definitions in memory. After modifying .mcp.json, the runtime continues using the old schema until you force a refresh. Restart Codex or use the plugin reload commands to re-read the configuration from disk. This is a common issue when adding new tools to existing plugins.

How do I verify if my MCP server is reachable?

For HTTP endpoints, use curl to send a POST request to the server URL with a valid JSON-RPC body. For local command-based servers, execute the command and args manually from the directory specified in cwd. If the command fails in the terminal, it will fail in Codex with the same error.

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