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

> Learn how to validate MCP configurations for OpenAI plugins in 3 simple steps. Ensure file presence, lint against the schema, and verify server connectivity.

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

---

**Validating MCP configurations for OpenAI plugins requires confirming that a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file exists at the plugin root, linting its JSON structure against the `mcpServers` schema in [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) file at the plugin root. The plugin manifest ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)) points to this file through the `mcpServers` field. The [`README.md`](https://github.com/openai/plugins/blob/main/README.md) at the repository root (lines 5–8) explains this layout and shows the [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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:

```bash
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`](https://github.com/openai/plugins/blob/main/./.mcp.json) and lists available tools to confirm the server is online:

```javascript
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`](https://github.com/openai/plugins/blob/main/plugins/shopify/skills/shopify-admin/SKILL.md) file shows the canonical command on line 34:

```bash
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`](https://github.com/openai/plugins/blob/main/.mcp.json) is present at the plugin root:

```bash
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:

```bash
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:

```bash
shopify app config validate --json

```

### Refresh the Agent Cache

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

```bash
codex restart

```

## Code Examples for Common Scenarios

### Minimal [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

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

```javascript
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:

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

```

## Summary

- A [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file must live at the plugin root and be referenced by [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) in OpenAI plugins?

The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json), as outlined in the repository's [`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.