Does MCP Relate to Manifest Files in OpenAI Plugins?

MCP (Model Context Protocol) and plugin manifest files serve complementary but distinct roles in the OpenAI Plugins architecture—while the manifest provides static metadata for plugin registration, MCP enables dynamic, structured tool-calling at runtime.

The OpenAI Plugins repository (openai/plugins) defines plugin capabilities through JSON manifests and runtime protocols that power the Codex system. Understanding the relationship between these components is essential for developers building AI agents that interact with external services.

What Are OpenAI Plugin Manifest Files?

Every plugin in the repository is described by a plugin manifest—a JSON file that contains static metadata the Codex runtime uses to initialize and load the plugin.

Location and Structure

The manifest resides at a fixed path within each plugin directory:

plugins/<plugin-name>/.codex-plugin/plugin.json

According to the repository README.md, this file is required for the Codex runtime to recognize the plugin.

Manifest Contents

The plugin.json file defines:

• Plugin metadata: name, description, version, and author information
• Skill entry-points: locations of executable skills and commands
• Assets: static resources and configuration parameters

This file is checked into version control and changes only when the plugin's fundamental capabilities evolve.

Understanding MCP (Model Context Protocol)

MCP is a runtime protocol that enables AI agents to discover and invoke tools—including functions, REST endpoints, and custom services—through a structured, standardized interface. Unlike the static manifest, MCP operates dynamically during agent execution.

Crucially, MCP definitions are not stored inside the plugin manifest. Instead, they are provided through separate channels that the agent accesses at runtime.

Key Differences Between Manifests and MCP

Aspect	Plugin Manifest (plugin.json)	MCP
Purpose	Static description of the plugin (metadata, skill locations, commands)	Dynamic, structured tool-calling protocol for agents
Location	plugins/<name>/.codex-plugin/plugin.json (checked into the repo)	Defined in skill docs, optional .mcp.json, or hosted MCP server
Usage	Read by the Codex runtime to load the plugin	Consumed by AI agents at execution time to invoke tools
Update Frequency	Changed when plugin capabilities evolve	Updated when new tool definitions or API endpoints are added; often generated automatically

Where MCP Definitions Live in OpenAI Plugins

Since MCP is not embedded in the manifest, it is defined through alternative mechanisms within the plugin structure.

Skill Documentation Files

Many skills reference MCP capabilities within their SKILL.md documentation. For example, the Wix headless skill in plugins/wix/skills/wix-app/SKILL.md (lines 33-36) mentions "MCP discovery" when an API reference is missing. Similarly, the Vercel API skill at plugins/vercel/skills/vercel-api/SKILL.md (lines 26-33) explicitly documents how to use MCP tools for deployment management.

Separate MCP Configuration Files

MCP tool schemas may also be defined in:

• .mcp.json files within plugin directories that define tool schemas
• Hosted MCP servers that the skill imports at runtime to access external APIs

These configurations allow plugins to expose dynamic capabilities without modifying the core plugin.json manifest.

Practical Implementation Examples

Reading a Plugin Manifest

To load plugin metadata programmatically from the Codex repository, read the JSON file from the .codex-plugin directory:

import { readFile } from "fs/promises";
import path from "path";

async function loadManifest(pluginName) {
  const manifestPath = path.join(
    "plugins",
    pluginName,
    ".codex-plugin",
    "plugin.json"
  );
  const raw = await readFile(manifestPath, "utf8");
  return JSON.parse(raw);
}

// Example: load the Wix plugin manifest
loadManifest("wix").then(console.log);

Calling an MCP-Defined Tool

To invoke tools exposed via MCP, use an MCP client with the appropriate endpoint:

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

async function listDeployments(projectId: string) {
  const mcp = await createMCPClient({ baseUrl: "https://api.vercel.com/mcp" });
  const result = await mcp.callTool("list_deployments", { projectId });
  return result.deployments;
}

Summary

• Plugin manifests (plugin.json) contain static metadata and reside in plugins/<name>/.codex-plugin/
• MCP is a runtime protocol for tool-calling that is not stored in manifest files
• MCP definitions appear in SKILL.md documentation (e.g., plugins/wix/skills/wix-app/SKILL.md and plugins/vercel/skills/vercel-api/SKILL.md), .mcp.json files, or hosted servers
• The manifest tells the Codex system what a plugin is, while MCP tells AI agents how to interact with external services at runtime
• Both components work together but remain in distinct files with different update cycles

Frequently Asked Questions

Is MCP defined inside the plugin.json manifest?

No. MCP definitions are kept separate from the plugin manifest. The plugin.json file located at plugins/<plugin-name>/.codex-plugin/plugin.json contains only static metadata such as the plugin name, version, and skill paths. MCP tool schemas and endpoints are defined in skill documentation or separate configuration files.

Can a single plugin use both a manifest and MCP?

Yes. This is the standard architecture in the OpenAI Plugins repository. The manifest registers the plugin with the Codex runtime, while individual skills within that plugin may leverage MCP for dynamic API discovery and tool invocation. The Vercel plugin exemplifies this pattern by using its manifest for registration and MCP for deployment management.

Where should I define MCP tools for my OpenAI plugin?

Define MCP tools in one of three locations: within your skill's SKILL.md documentation for human-readable references, in a dedicated .mcp.json file for structured schemas, or via a hosted MCP server that your plugin imports at runtime. The Vercel skill uses the documentation approach, while other plugins may use dedicated configuration files depending on whether they need automatic discovery or external hosting.

How do SKILL.md files reference MCP functionality?

SKILL.md files reference MCP to indicate how agents should discover and invoke external APIs when standard documentation is insufficient. For instance, plugins/wix/skills/wix-app/SKILL.md (lines 33-36) mentions MCP discovery when API references are missing, while plugins/vercel/skills/vercel-api/SKILL.md (lines 26-33) explicitly documents MCP tool calls for listing deployments and managing projects.

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