# How to Debug MCP Settings in OpenAI Plugins: A Complete Troubleshooting Guide

> Debug MCP settings in OpenAI plugins effectively. Verify JSON configs, validate env vars, test endpoints, and enable verbose logging to solve authentication and tool definition issues.

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

---

**Debug MCP settings in OpenAI plugins by verifying `*.mcp.json` configuration files, validating environment variables like `VERCEL_TOKEN`, testing endpoints with raw HTTP requests, and enabling `DEBUG=mcp:*` verbose logging to isolate authentication failures and missing tool definitions.**

The **Model Context Protocol (MCP)** is the standardized interface that OpenAI plugins use to discover and invoke external services such as Vercel, Cloudflare, and Wix. When MCP settings are misconfigured, issues typically surface as missing tools, authentication errors, or unexpected fallbacks to legacy CLI calls. This guide walks through the exact debugging workflow used in the `openai/plugins` repository to identify and resolve these failure points.

## Understanding the MCP Flow in OpenAI Plugins

The MCP implementation follows a four-stage pipeline defined in the plugin source code:

- **Load MCP config**: The system reads `*.mcp.json` files (e.g., [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json)) to discover available tools and endpoints.
- **Create MCP client**: The code calls `createMCPClient` from `@ai-sdk/mcp`, typically configured in skill documentation such as [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md).
- **Invoke tools**: The client executes remote tools like `list_projects` or `get_runtime_logs` through the MCP protocol.
- **Fallback handling**: When MCP tools are unavailable, the plugin falls back to CLI or direct REST calls as documented in [`plugins/vercel/skills/vercel-cli/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md).

Understanding this execution chain helps isolate whether failures originate from configuration, authentication, or network connectivity.

## Common MCP Failure Modes

MCP-related issues in OpenAI plugins typically manifest in specific patterns:

| Symptom | Likely Cause | Quick Verification |
|---------|--------------|-------------------|
| **"Tool not found"** | Missing tool definition in MCP server metadata | Verify the `tools` array in the plugin's `*.mcp.json` contains the expected name |
| **Authentication errors** (`401`/`403`) | Outdated or missing OAuth tokens | Check the `auth` block in [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) and confirm environment variables like `VERCEL_TOKEN` are set |
| **Network timeouts** | Unreachable MCP server endpoint | Run `curl` against the URL specified in `*.mcp.json` under `endpoint` |
| **Schema mismatches** | Mismatched input/output definitions | Compare `inputSchema`/`outputSchema` in the skill file against the server's [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) |
| **Unexpected CLI fallback** | MCP server missing specific capabilities | Review the "MCP-first, CLI-fallback" comments in [`plugins/vercel/skills/vercel-cli/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md) |

## Step-by-Step MCP Debugging Workflow

Follow this systematic approach to diagnose MCP configuration issues:

1. **Locate and validate the MCP configuration**

   Examine the plugin's MCP JSON file to confirm valid syntax and correct endpoints:

   ```bash
   cat plugins/cloudflare/.mcp.json
   ```

   Ensure the file contains a valid `endpoint` URL and a populated `tools` array.

2. **Verify environment variables**

   Most MCP clients read credentials from environment variables. Confirm that required tokens (e.g., `VERCEL_TOKEN`, `CLOUDFLARE_API_TOKEN`) are exported in your shell or `.env` file according to the specifications in the skill documentation.

3. **Test the endpoint directly**

   Bypass the client library to verify server reachability:

   ```bash
   curl -H "Authorization: Bearer $VERCEL_TOKEN" \
        $MCP_ENDPOINT/tools/list_projects
   ```

   Success indicates the issue lies in the client wrapper; failure points to server or credential problems.

4. **Inspect client initialization**

   Review how the MCP client is instantiated in your skill code:

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

   const mcpClient = await createMCPClient({
     endpoint: process.env.MCP_ENDPOINT,
     auth: { token: process.env.VERCEL_TOKEN },
   });
   ```

   Ensure the `endpoint` and `auth` parameters match your configuration from step 1.

5. **Enable verbose logging**

   Set the environment variable to trace MCP requests:

   ```bash
   DEBUG=mcp:* node my-plugin.js
   ```

   This exposes full request URLs, headers, and JSON responses to identify malformed payloads or missing authentication headers.

6. **Check fallback behavior**

   If MCP calls fail, observe whether the plugin logs `>>> Falling back to @vercel/cli`. Verify that the locally installed CLI version supports the required sub-commands.

7. **Validate MCP server version**

   If you control the MCP server, ensure it runs MCP spec v1.2 or later. Older versions may omit new tools, causing "tool not found" errors even when the client configuration is correct.

8. **Run built-in diagnostics**

   Many plugins provide status commands for MCP health checks:

   ```bash
   vercel status --mcp
   ```

   This command, documented in [`plugins/vercel/commands/status.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/status.md), lists available tools, endpoint reachability, and token validity.

## Practical Code Examples for MCP Debugging

### Creating an MCP Client

The following pattern from [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) demonstrates proper client initialization:

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

async function getMcpClient() {
  const client = await createMCPClient({
    endpoint: process.env.MCP_ENDPOINT,
    auth: { token: process.env.VERCEL_TOKEN },
  });
  return client;
}

(async () => {
  const client = await getMcpClient();
  const projects = await client.call("list_projects", {});
  console.log("Projects:", projects);
})();

```

### Implementing CLI Fallback Logic

When MCP tools are unavailable, implement graceful degradation as shown in the Vercel CLI skill:

```javascript
async function listProjects() {
  try {
    const client = await getMcpClient();
    return await client.call("list_projects", {});
  } catch (e) {
    console.warn("MCP tool unavailable, falling back to CLI:", e.message);
    const { execSync } = require("child_process");
    const out = execSync("npx @vercel/cli projects list --json", {
      encoding: "utf-8",
    });
    return JSON.parse(out);
  }
}

```

### Enabling Debug Output

For tracing request/response cycles:

```bash
DEBUG=mcp:* node my-plugin.js

```

This outputs the complete HTTP traffic between the client and MCP server, revealing schema mismatches or authentication header omissions.

## Key Files for MCP Configuration Debugging

Understanding these specific files in the `openai/plugins` repository accelerates troubleshooting:

- **[`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json)**: Defines the Cloudflare MCP server endpoint and exposed tools inventory
- **[`plugins/vercel/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.mcp.json)**: Serves as the source of truth for Vercel MCP server capabilities
- **[`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md)**: Contains the `createMCPClient` implementation and authentication patterns
- **[`plugins/vercel/skills/vercel-cli/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md)**: Documents the CLI fallback path when MCP is unavailable
- **[`plugins/wix/skills/wix-app/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/SKILL.md)**: Demonstrates the "API-first, MCP-for-gaps" pattern common across plugins
- **[`plugins/vercel/commands/status.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/status.md)**: Provides the `vercel status --mcp` diagnostic command
- **[`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/build-ios-apps/.mcp.json)**: Reference implementation for cross-plugin MCP consistency

## MCP Debugging Checklist

Before deploying or debugging further, verify:

- [ ] `*.mcp.json` exists and contains valid JSON with a reachable `endpoint` URL
- [ ] Environment variables (`MCP_ENDPOINT`, provider-specific tokens) are defined and current
- [ ] `@ai-sdk/mcp` package is updated to version 1.0 or later
- [ ] Raw `curl` requests to the MCP endpoint return HTTP 200 with a valid `tools` list
- [ ] Tool names and schemas in skill files match the server's [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) definitions exactly
- [ ] `DEBUG=mcp:*` logging shows no hidden network or parsing errors
- [ ] Fallback CLI commands execute successfully when MCP is bypassed

## Summary

Debugging MCP settings in OpenAI plugins requires systematic verification of configuration files, environment variables, and network connectivity:

- **Verify configuration** by inspecting `*.mcp.json` files in plugin directories like `plugins/cloudflare/` and `plugins/vercel/`
- **Test connectivity** using raw HTTP requests to the MCP endpoint before troubleshooting client code
- **Check authentication** by confirming environment variables match the requirements in skill documentation such as [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md)
- **Enable verbose logging** with `DEBUG=mcp:*` to expose request/response details and schema mismatches
- **Validate fallbacks** when MCP tools are unavailable by reviewing CLI fallback logic in [`plugins/vercel/skills/vercel-cli/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md)

## Frequently Asked Questions

### What does "Tool not found" mean in MCP?

The "Tool not found" error indicates that the requested tool name does not exist in the MCP server's discovery metadata. According to the source code in `openai/plugins`, this occurs when the `tools` array in the plugin's [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file lacks the specific tool entry, or when the server is running an outdated MCP spec version that excludes newer tools. Verify the tool name matches exactly between your client call and the server configuration.

### How do I check if my MCP endpoint is working?

Test the endpoint using a raw HTTP request with the appropriate authorization header. Execute `curl -H "Authorization: Bearer $YOUR_TOKEN" $MCP_ENDPOINT/tools/list` to verify the server returns a JSON response containing the available tools list. If this request fails with a network error or authentication failure, the issue lies with server reachability or credentials rather than your plugin code.

### Why does my plugin fall back to CLI instead of using MCP?

The plugin falls back to CLI execution when the MCP client throws an error, typically because the requested tool is not listed in the server's capabilities or the MCP endpoint is unreachable. As implemented in [`plugins/vercel/skills/vercel-cli/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md), this "MCP-first, CLI-fallback" pattern ensures continuity of service. Check the logs for `>>> Falling back to` messages, then verify the tool exists in the corresponding [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file and that the MCP server is online.

### Where are MCP environment variables configured?

MCP environment variables such as `VERCEL_TOKEN`, `CLOUDFLARE_API_TOKEN`, and `MCP_ENDPOINT` are configured in your shell environment or a local `.env` file. The `createMCPClient` function in [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) reads these values via `process.env`. Ensure these variables are exported before starting the plugin, as the MCP client initialization depends on them for authentication and endpoint discovery.