How to Validate MCP Configurations for OpenAI Plugins: A 3-Step Guide

Validating MCP configurations for OpenAI plugins requires confirming that a .mcp.json file exists at the plugin root, linting its JSON structure against the mcpServers schema in plugin.json, and pinging the MCP server endpoint to verify connectivity and tool discovery.

OpenAI plugins in the openai/plugins repository rely on a Model-Context-Protocol (MCP) server to expose structured tool calls for AI agents. A valid MCP configuration is required for the plugin runtime to discover and invoke those tools reliably. This guide walks through the exact validation stages using source files and methods implemented in the repository.

Locate the MCP Configuration File

Every plugin must contain a .mcp.json file at the plugin root. The plugin manifest (plugin.json) points to this file through the mcpServers field. The README.md at the repository root (lines 5–8) explains this layout and shows the .mcp.json reference.

Verify the JSON Structure

The file must be valid JSON and contain at least a server URL, for example "https://mcp.my-service.com". Optional fields include auth, which can specify OAuth scopes or an API-key name. The .agents/skills/plugin-creator/references/plugin-json-spec.md file defines the mcpServers property and its expected shape on line 65. Malformed JSON or a missing URL causes the plugin loader to abort before any tool can be discovered.

Test Connectivity and Capabilities

Validation must go beyond syntax. Run static, dynamic, and tool-specific checks to guarantee the server is reachable and returns well-formed responses.

Run a Static Syntax Check

Use any JSON linter to catch structural errors before runtime. The jq utility exits with code 0 on valid input:

jq empty .mcp.json

Run a Dynamic Health Check

Instantiate an MCP client using @ai-sdk/mcp and call a lightweight endpoint. The Vercel skill demonstrates this client pattern around lines 307–315. The following Node.js script reads ./.mcp.json and lists available tools to confirm the server is online:

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

async function pingMCP() {
  const client = await createMCPClient({ configPath: "./.mcp.json" });
  const tools = await client.listTools({ maxResults: 1 });
  console.log("MCP reachable – tools:", tools);
}

pingMCP().catch(err => console.error("MCP validation failed:", err));

If this call throws, the URL is wrong, the server is down, or the auth details are missing.

Run Tool-Specific Validators

Some plugins ship their own validation CLI to catch domain-level misconfigurations. For Shopify plugins, the plugins/shopify/skills/shopify-admin/SKILL.md file shows the canonical command on line 34:

shopify app config validate --json

This parses the local configuration and reports schema violations before shopify app dev or shopify app deploy is executed.

Complete Validation Workflow

Follow these ordered steps to fully validate an MCP configuration for your OpenAI plugin.

Confirm the File Exists

Verify .mcp.json is present at the plugin root:

if [[ -f .mcp.json ]]; then echo "MCP config found"; else echo "Missing .mcp.json"; fi

Lint the JSON

Run jq to confirm the file is valid JSON:

jq empty .mcp.json

Ping the MCP Server

Execute the Node.js health-check script from the dynamic check section above. A successful listTools call proves the runtime can discover tools.

Run a Domain-Level Validator

For Shopify-based plugins, invoke the CLI validator before deployment:

shopify app config validate --json

Refresh the Agent Cache

After fixing the file, restart the agent cache so the changes propagate:

codex restart

Code Examples for Common Scenarios

Minimal .mcp.json

Place this file at the root of the plugin directory. It provides the runtime with the server endpoint and OAuth scopes needed for authentication:

{
  "server": "https://mcp.example.com",
  "auth": {
    "type": "oauth",
    "scopes": ["read:tools", "write:tools"]
  }
}

Programmatic Validation in Node.js

This script calls the health tool and lists the first five tools to verify schema propagation:

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

async function validateMCP() {
  try {
    const client = await createMCPClient({ configPath: "./.mcp.json" });
    await client.callTool("health", {});
    const { tools } = await client.listTools({ maxResults: 5 });
    console.log("MCP tools discovered:", tools.map(t => t.name));
  } catch (e) {
    console.error("MCP validation error:", e);
    process.exit(1);
  }
}

validateMCP();

Shell-Based Validation with Shopify

Run the Shopify CLI and exit on failure:

shopify app config validate --json || {
  echo "Shopify config validation failed"
  exit 1
}
echo "Shopify config is valid"

Summary

• A .mcp.json file must live at the plugin root and be referenced by plugin.json through the mcpServers field.
• Validate syntax with jq empty .mcp.json before attempting runtime checks.
• Use createMCPClient from @ai-sdk/mcp to dynamically verify server connectivity and tool discovery.
• Leverage domain-specific validators like shopify app config validate --json when available.
• Restart the agent cache after correcting configuration errors.

Frequently Asked Questions

What is the role of .mcp.json in OpenAI plugins?

The .mcp.json file stores the Model-Context-Protocol server URL and authentication details required for the plugin runtime to discover and invoke tools. It must reside at the plugin root and be referenced by the mcpServers field in plugin.json, as outlined in the repository's README.md.

Can I validate an MCP configuration without running the full plugin?

Yes. Run jq empty .mcp.json for a static syntax check, then use @ai-sdk/mcp to instantiate a client and call listTools or health against the server URL. These checks do not require the full plugin environment to be active, so you can validate configuration changes in isolation.

Where is the mcpServers schema officially defined?

The schema is documented in .agents/skills/plugin-creator/references/plugin-json-spec.md at line 65 in the openai/plugins repository. It specifies the expected shape of the mcpServers property inside plugin.json, including required and optional fields.

What should I do if the MCP server is unreachable during validation?

First, verify the server URL in .mcp.json is correct and reachable from your network. Next, check that any required auth credentials or OAuth scopes are present and valid. If the server is online but tool discovery fails, confirm the MCP server implements the standard listTools endpoint as expected by the @ai-sdk/mcp client.

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