# Troubleshooting MCP Configuration Errors in OpenAI Plugins: A Complete Guide

> Troubleshoot MCP configuration errors in OpenAI plugins with this guide. Learn to fix common issues like missing files, bad JSON, server problems, and authentication tokens.

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

---

**Most MCP configuration errors in OpenAI plugins stem from missing [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file at its root, adjacent to the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest.

### The .mcp.json File Location and Format

Codex scans for [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json), the configuration defines a local Node.js server:

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

```

Contrast this with [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json), which points to a remote HTTP endpoint:

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

```bash
node ./mcp/server.mjs

```

For remote servers, verify reachability with `curl`:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/daloopa/skills/setup/SKILL.md), you must reload the plugin to flush the cache:

```bash
codex plugin unload daloopa
codex plugin load daloopa

```

Alternatively, restart the Codex process entirely to force a fresh scan of [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json).

## Step-by-Step Diagnostic Workflow

The troubleshooting methodology in [`plugins/moody-s/skills/moody-s-explore-mcp/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md) or custom internal tools.

## Summary

- **Configuration errors** trace back to the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.