MCP Requirements for OpenAI Plugin Development: The Complete Technical Guide

OpenAI plugins must provide a .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)

Every MCP-enabled plugin must include a .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 (lines 231-235), these schema definitions enable the MCP server to validate agent-generated calls at runtime against strict JSON Schema definitions.

{
  "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

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 (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 (lines 286-295) illustrates this pattern by specifying OAuth scopes without exposing bearer tokens or API keys.

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 (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 (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 (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 (lines 22-30) demonstrate this pattern by attempting MCP calls first, then catching exceptions to trigger REST API fallbacks using environment variables for authentication.

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

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