Where to Find MCP Documentation for OpenAI Plugin Development

The OpenAI plugins repository centralizes MCP documentation in skill markdown files for Vercel and Cloudflare, links to the official Model Context Protocol specification, and defines machine-readable contracts in .mcp.json manifests.

The openai/plugins repository serves as the primary source for plugin authors integrating the Model Context Protocol (MCP) into OpenAI-powered tools. Rather than duplicating the full protocol specification, the repository embeds targeted guides inside skill directories and references the canonical MCP spec for complete schema and transport details.

Primary MCP Documentation Locations

Vercel API Skill: The Main Integration Guide

The most comprehensive MCP documentation lives in plugins/vercel/skills/vercel-api/SKILL.md. This file provides a concrete MCP integration example, covering transport details, OAuth flows, and a complete table of available MCP tools.

According to the source, it also links directly to the official MCP specification at https://spec.modelcontextprotocol.io and the Vercel-specific MCP documentation at https://vercel.com/docs/mcp. This makes it the definitive starting point for understanding how agents should call MCP-exposed tools within the OpenAI plugin ecosystem.

Cloudflare Skill: Building Custom MCP Servers

For developers building from scratch, plugins/cloudflare/skills/building-mcp-server-on-cloudflare/SKILL.md documents how to construct a custom MCP server on Cloudflare. It includes the spec URL, transport configuration, and security best-practices.

This skill explicitly references the Model Context Protocol website at https://modelcontextprotocol.io, giving plugin authors the entry point they need for general protocol overviews and spec navigation.

OpenAI Developers Skill: Schema Enforcement Rules

The file plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md enforces strict compliance with MCP tool descriptors. It mandates that agents use exact inputSchema and outputSchema definitions and points to the MCP specification for proper tool definitions.

This establishes the no-invent-schemas rule, ensuring consistent MCP usage across all plugins and preventing arbitrary schema generation that would break interoperability.

Machine-Readable MCP Manifests (.mcp.json)

Alongside human-readable guides, the repository stores machine-readable contracts in .mcp.json files. These JSON manifests declare MCP endpoints, OAuth scopes, and supported tool schemas for each plugin.

Key manifests include:

• plugins/vercel/.mcp.json — Defines the Vercel MCP endpoint and available tools.
• plugins/cloudflare/.mcp.json — Describes the Cloudflare MCP server configuration.
• plugins/build-ios-apps/.mcp.json — Demonstrates MCP manifest usage for non-web tooling.

These files serve as the contract that an MCP client consumes to discover and authenticate with a plugin's capabilities.

External MCP Specifications and References

The repository intentionally avoids duplicating the full protocol specification. Instead, it links to three canonical resources that serve as the source of truth for protocol-level details:

• MCP Specification (https://spec.modelcontextprotocol.io) — The canonical transport and schema protocol description.
• Vercel MCP Documentation (https://vercel.com/docs/mcp) — Platform-specific guidance on exposing MCP tools.
• Model Context Protocol Website (https://modelcontextprotocol.io) — General overview and spec navigation.

Plugin authors should treat these external links as the definitive reference while using the repository's skill files for implementation patterns.

How to Consume MCP in Plugin Skills

The Vercel skill provides idiomatic patterns for consuming MCP in TypeScript. The following examples demonstrate how to initialize a client, call tools, handle fallbacks, and register commands.

Creating an MCP Client

Use the @ai-sdk/mcp package to instantiate a client pointing to the MCP server endpoint:

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

const mcp = await createMCPClient({
  // URL of the MCP server (provided by the connected Vercel app)
  endpoint: "https://mcp.vercel.com",
  // OAuth token is fetched automatically on first use
});

This pattern matches the implementation shown in the Vercel skill.

Calling an MCP-Exposed Tool

Once connected, invoke tools by name using the exact identifiers defined in the .mcp.json schema:

// The tool name matches the one defined in the MCP schema
const deployments = await mcp.callTool("list_deployments", {
  limit: 5,
  // optional filters …
});

console.log("Recent deployments:", deployments);

The skill uses list_deployments as a canonical example of querying deployment data through the protocol.

Falling Back to REST When a Tool Is Missing

When an MCP tool is unavailable, fallback logic should use the platform's native SDK:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({ bearerToken: process.env.VERCEL_TOKEN });
const { deployments } = await vercel.deployments.list({ limit: 5 });

This pattern appears in the Vercel skill's SDK Examples section and ensures resilience when MCP endpoints fail or lack coverage.

Registering an MCP Command in .app.json

Map user-facing commands to MCP tools in the plugin manifest:

{
  "name": "my-plugin",
  "commands": {
    "list-deployments": {
      "type": "mcp",
      "tool": "list_deployments",
      "description": "Show the latest Vercel deployments"
    }
  }
}

The command schema in .app.json connects to the tool definitions stored in .mcp.json, creating a complete chain from user intent to protocol execution.

Summary

• MCP documentation for OpenAI plugin development is distributed across skill markdown files in the openai/plugins repository rather than centralized in a single doc.
• plugins/vercel/skills/vercel-api/SKILL.md provides the most complete integration guide, including transport, OAuth, and tool tables.
• plugins/cloudflare/skills/building-mcp-server-on-cloudflare/SKILL.md covers custom server construction and security practices.
• plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md enforces strict inputSchema and outputSchema compliance with the no-invent-schemas rule.
• .mcp.json manifests, such as plugins/vercel/.mcp.json, supply the machine-readable contracts that MCP clients consume.
• The repository links to canonical external resources—spec.modelcontextprotocol.io, vercel.com/docs/mcp, and modelcontextprotocol.io—for protocol-level authority.

Frequently Asked Questions

Where is the main MCP documentation file in the openai/plugins repository?

The primary documentation is located in plugins/vercel/skills/vercel-api/SKILL.md. This file contains transport details, OAuth flows, an available tool table, and direct links to the official MCP specification and Vercel MCP docs.

Does the openai/plugins repository host the full MCP specification?

No. The repository links to the canonical external spec at https://spec.modelcontextprotocol.io rather than duplicating it. Internal documentation focuses on integration patterns, schema enforcement, and platform-specific examples.

What is the purpose of .mcp.json files in OpenAI plugin development?

Files like plugins/vercel/.mcp.json act as machine-readable manifests. They declare MCP endpoints, OAuth scopes, and supported tool schemas, allowing MCP clients to discover and authenticate with a plugin's capabilities automatically.

How does the repository enforce consistent MCP tool definitions?

The plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md file enforces the no-invent-schemas rule. It requires that all MCP tools use exact inputSchema and outputSchema descriptors and point to the official specification for compliance, preventing arbitrary schema drift across plugins.

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