# Where to Find MCP Documentation for OpenAI Plugin Development

> Find MCP documentation for OpenAI plugin development within the openai plugins repository. Access skill markdown files, the official Model Context Protocol spec, and .mcp.json manifests.

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

---

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

Alongside human-readable guides, the repository stores machine-readable contracts in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/vercel/.mcp.json) — Defines the Vercel MCP endpoint and available tools.
- [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) — Describes the Cloudflare MCP server configuration.
- [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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:

```typescript
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`](https://github.com/openai/plugins/blob/main/.mcp.json) schema:

```typescript
// 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:

```typescript
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`](https://github.com/openai/plugins/blob/main/.app.json)

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

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

```

The command schema in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) connects to the tool definitions stored in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/skills/chatgpt-app-submission/SKILL.md) enforces strict `inputSchema` and `outputSchema` compliance with the no-invent-schemas rule.
- [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) manifests, such as [`plugins/vercel/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) files in OpenAI plugin development?

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