# MCP Requirements for OpenAI Plugin Development: The Complete Technical Guide

> Discover MCP requirements for OpenAI plugin development. Master .mcp.json manifests, OAuth authentication with @ai-sdk/mcp client, and REST/CLI fallbacks for seamless integration. Get the complete technical guide.

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

---

**OpenAI plugins must provide a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) manifest with schema-aligned tool definitions, use OAuth-based authentication via the `@ai-sdk/mcp` client, and implement REST/CLI fallbacks to satisfy Model Context Protocol requirements.**

The `openai/plugins` repository defines strict architectural standards for integrating the Model Context Protocol (MCP) into AI agent plugins. These requirements ensure that tools remain discoverable, secure, and backward-compatible across diverse deployment environments while preventing credential leakage.

## MCP Manifest Structure ([`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json))

Every MCP-enabled plugin must include a **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** file at the repository root that serves as the machine-readable contract for AI agents. This JSON manifest describes each tool with specific fields including `name`, `description`, `inputSchema`, `outputSchema`, authentication configuration, and rate limits.

Unlike legacy plugin definitions that use `parameters` and `result` fields, MCP-compliant tools must use **`inputSchema`** and **`outputSchema`** to guarantee type safety. According to the Vercel plugin implementation in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) (lines 231-235), these schema definitions enable the MCP server to validate agent-generated calls at runtime against strict JSON Schema definitions.

```json
{
  "tools": [
    {
      "name": "list_projects",
      "description": "Return a list of Vercel projects the user has access to.",
      "inputSchema": { "type": "object", "properties": {}, "required": [] },
      "outputSchema": {
        "type": "object",
        "properties": {
          "projects": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Project" }
          }
        },
        "required": ["projects"]
      },
      "auth": { "type": "oauth", "scopes": ["project:read"] },
      "maxResults": 5
    }
  ]
}

```

*Reference: [`plugins/vercel/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.mcp.json)*

## Authentication and Security Standards

MCP tools must **never embed secrets or raw API keys** in the manifest definition. Instead, plugins rely on the **`@ai-sdk/mcp`** client to handle OAuth token exchange automatically at runtime. As demonstrated in [`plugins/wix/skills/wix-headless/references/shared/AUTHENTICATION.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/shared/AUTHENTICATION.md) (lines 3-8), the manifest should contain only OAuth scope definitions while the client manages credential acquisition securely.

This approach satisfies the repository's primary security policy of keeping authentication details out of the MCP definition. The Vercel skill configuration in [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) (lines 286-295) illustrates this pattern by specifying OAuth scopes without exposing bearer tokens or API keys.

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

export async function listProjects() {
  const client = await createMCPClient();        // OAuth handled automatically
  const result = await client.callTool("list_projects", {});
  return result.projects;                        // Typed as Project[]
}

```

*Reference: [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) (lines 307-315)*

## Schema Versioning and Result Limits

To maintain backward compatibility, MCP manifests must support **versioned tool definitions**. When APIs evolve, the manifest should retain legacy schema definitions while introducing new versions, allowing agents to continue using stable contracts. The Wix plugin references this requirement in [`plugins/wix/skills/wix-app/references/STORES_VERSIONING.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/references/STORES_VERSIONING.md) (line 332), which discusses MCP as the mechanism for versioned behavior fallback.

Additionally, MCP search operations should specify conservative **`maxResults`** values (commonly 5) to prevent overwhelming agents with large result sets. The Wix app skill in [`plugins/wix/skills/wix-app/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/SKILL.md) (line 345) explicitly implements this limit to ensure lightweight, performant responses that fit within context windows.

## Resilience and Fallback Patterns

Production MCP implementations must implement an **"MCP-first" strategy** with automatic fallback to REST or CLI interfaces. When the MCP server is unavailable or a specific tool is missing from the manifest, the plugin should degrade gracefully to direct API calls or command-line execution without breaking the user experience.

The Vercel command conventions in [`plugins/vercel/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/_conventions.md) (lines 22-30) demonstrate this pattern by attempting MCP calls first, then catching exceptions to trigger REST API fallbacks using environment variables for authentication.

```typescript
export async function listProjects() {
  try {
    const client = await createMCPClient();
    const { projects } = await client.callTool("list_projects", {});
    return projects;
  } catch (e) {
    // MCP missing or error – fall back to Vercel REST API
    const resp = await fetch("https://api.vercel.com/v9/projects", {
      headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
    });
    const data = await resp.json();
    return data.projects;
  }
}

```

*Reference: [`plugins/vercel/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/_conventions.md) (lines 22-30)*

## Documentation Requirements

Every skill file must contain an explicit **"MCP Tools"** section documenting which operations are MCP-enabled and under what conditions. This documentation serves both human reviewers and automated validation tools scanning the repository. The Vercel API skill at [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md) (lines 38-45) enumerates its MCP tools, providing clear context for maintainers about which endpoints use the protocol versus traditional interfaces.

## Summary

- **Provide a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) manifest** at the repository root describing every tool with `inputSchema` and `outputSchema` fields, not legacy `parameters` definitions.
- **Use the `@ai-sdk/mcp` client** for all tool invocations, letting it handle OAuth token exchange automatically without embedding secrets in the manifest.
- **Implement MCP-first with REST/CLI fallback** to ensure resilience when MCP servers are unavailable or tools are undefined.
- **Omit all secrets** from MCP definitions; rely on runtime token acquisition through the official client.
- **Version tool definitions** to maintain backward compatibility, and limit result sets (typically to 5 items) to prevent context overflow.
- **Document MCP usage** explicitly in skill Markdown files to enable automated validation and reviewer understanding.

## Frequently Asked Questions

### What file format is required for MCP manifests in OpenAI plugins?

OpenAI plugins require a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file at the repository root containing a JSON object with a `tools` array. Each tool must define `name`, `description`, `inputSchema`, `outputSchema`, and authentication configuration using the OAuth type specification.

### How does authentication work with MCP in OpenAI plugins?

Authentication flows through the `@ai-sdk/mcp` client, which automatically handles OAuth token exchange at runtime. The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) manifest specifies only OAuth scopes (e.g., `"scopes": ["project:read"]`) without containing actual tokens or API keys, preventing credential leakage in version control.

### Can OpenAI plugins use both MCP and traditional REST APIs simultaneously?

Yes, plugins must implement a fallback strategy where they attempt MCP calls first, then catch exceptions to trigger direct REST API or CLI commands. This pattern appears in [`plugins/vercel/commands/_conventions.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/_conventions.md), ensuring tools remain functional in environments without MCP server deployment.

### What schema fields are required in the MCP manifest?

MCP manifests must use **`inputSchema`** and **`outputSchema`** (JSON Schema objects) rather than the legacy `parameters` and `result` fields. These schemas enable runtime validation of agent-generated calls and ensure type-safe interactions between AI agents and external services.