how-to-guide

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

June 6, 2026 openai/plugins ↗

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) 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.
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.

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` 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`
Unexpected CLI fallback	MCP server missing specific capabilities	Review the "MCP-first, CLI-fallback" comments in `plugins/vercel/skills/vercel-cli/SKILL.md`

Step-by-Step MCP Debugging Workflow

Follow this systematic approach to diagnose MCP configuration issues:

Locate and validate the MCP configuration

Examine the plugin's MCP JSON file to confirm valid syntax and correct endpoints:
```
cat plugins/cloudflare/.mcp.json
```
Ensure the file contains a valid endpoint URL and a populated tools array.
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.
Test the endpoint directly

Bypass the client library to verify server reachability:
```
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.

Inspect client initialization

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

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.

Enable verbose logging

Set the environment variable to trace MCP requests:
```
DEBUG=mcp:* node my-plugin.js
```
This exposes full request URLs, headers, and JSON responses to identify malformed payloads or missing authentication headers.
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.
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.
Run built-in diagnostics

Many plugins provide status commands for MCP health checks:
```
vercel status --mcp
```
This command, documented in 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 demonstrates proper client initialization:

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:

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:

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: Defines the Cloudflare MCP server endpoint and exposed tools inventory
plugins/vercel/.mcp.json: Serves as the source of truth for Vercel MCP server capabilities
plugins/vercel/skills/ai-sdk/SKILL.md: Contains the createMCPClient implementation and authentication patterns
plugins/vercel/skills/vercel-cli/SKILL.md: Documents the CLI fallback path when MCP is unavailable
plugins/wix/skills/wix-app/SKILL.md: Demonstrates the "API-first, MCP-for-gaps" pattern common across plugins
plugins/vercel/commands/status.md: Provides the vercel status --mcp diagnostic command
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 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
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

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 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, 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 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 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how openai/plugins works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →