Skill implementation automatically uses the App Connector

#.app.json vs .mcp.json in Codex Plugins: Understanding the Difference

.app.json configures public ChatGPT store integrations using OpenAI-managed connectors, while .mcp.json configures private Enterprise Store backends using custom MCP (Managed Cloud Platform) servers.

Codex plugins in the openai/plugins repository use these two distinct manifest files to define how external API communication is routed. Understanding the difference between .app.json and .mcp.json ensures you implement the correct integration pattern for your deployment target, whether you are publishing to the public store or building enterprise-grade internal tools.

What Do .app.json and .mcp.json Describe?

Both files reside in the plugin root directory, but they serve fundamentally different architectural purposes.

.app.json: The App Connector Manifest

The .app.json file defines an App Connector—a thin wrapper that points the plugin to a ready-made connector hosted by OpenAI. This connector provides a Cloud-hosted API surface that handles authentication, request routing, and scaling automatically.

Key characteristics:

• Location: plugins/<plugin-name>/.app.json (e.g., plugins/linear/.app.json)
• Purpose: References a managed connector using a "connectorId" field
• Configuration: Contains static settings like OAuth scopes, default endpoints, and version constraints
• Deployment: Used for every plugin running on the public ChatGPT store

.mcp.json: The MCP Server Descriptor

The .mcp.json file describes a private MCP (Managed Cloud Platform) server for enterprise-only plugins. This file is required when you need to bypass the generic app connector and route traffic to a dedicated backend that you control.

Key characteristics:

• Location: plugins/<plugin-name>/.mcp.json (e.g., plugins/linear/.mcp.json)
• Purpose: Specifies a custom server URL, authentication method, and routing rules
• Configuration: Defines "serverUrl", "auth" headers, and custom proxy settings
• Deployment: Used exclusively for plugins running on the Enterprise Store or requiring dedicated infrastructure (e.g., FigJam integrations)

How plugin.json Resolves the Configuration

The runtime determines which manifest to load based on the top-level plugin.json file, typically located at plugins/<plugin>/.codex-plugin/plugin.json. This manifest declares which integration files are available:

{
  "apps": "./.app.json",
  "mcpServers": "./.mcp.json"
}

Resolution rules:

• If both keys are present, the runtime prefers the MCP definition for enterprise deployments
• The system falls back to the app connector for public store distributions
• At least one of these files must be referenced for the Codex runtime to route API calls

Practical Implementation Examples

Public Store Integration Using .app.json

When targeting the public ChatGPT store, define your connector in .app.json:

// File: plugins/linear/.app.json
{
  "$schema": "https://platform.openai.com/apps/schema.json",
  "connectorId": "linear",
  "version": "1.0.0",
  "config": {
    "scopes": ["read", "write"]
  }
}

Your skill code can then call the managed connector directly:

# Skill implementation automatically uses the App Connector

response = await client.post("/linear/v1/tasks", json={"title": "New task"})

Enterprise Store Integration Using .mcp.json

For enterprise deployments requiring a private backend, configure .mcp.json:

// File: plugins/linear/.mcp.json
{
  "$schema": "https://platform.openai.com/mcp/schema.json",
  "serverUrl": "https://mcp.mycompany.com/linear",
  "auth": {
    "type": "apiKey",
    "headerName": "X-API-Key"
  }
}

Your skill must then target the private MCP endpoint explicitly:

# Skill implementation targeting private MCP server

response = await client.post(
    "https://mcp.mycompany.com/linear/v1/tasks",
    headers={"X-API-Key": os.getenv("MCP_API_KEY")},
    json={"title": "Enterprise task"}
)

Key File Locations in the Repository

According to the openai/plugins source structure, these files follow a consistent pattern:

• plugins/<plugin-name>/.app.json — Public store connector manifest (e.g., plugins/linear/.app.json)
• plugins/<plugin-name>/.mcp.json — Enterprise MCP server descriptor (e.g., plugins/linear/.mcp.json)
• plugins/<plugin>/.codex-plugin/plugin.json — Top-level plugin definition that references the manifests
• README.md — Root documentation explaining the architectural distinction between app connectors and MCP servers

Summary

• .app.json configures public-store, managed connectors—the default zero-maintenance integration for the ChatGPT store
• .mcp.json configures enterprise-store, custom MCP servers—optional self-hosted backends for private use cases
• The runtime selects the appropriate configuration based on the deployment context when both files are declared in plugin.json
• App connectors handle OAuth and routing automatically, while MCP servers require manual endpoint management and authentication headers

Frequently Asked Questions

Can a Codex plugin use both .app.json and .mcp.json simultaneously?

Yes, a plugin can declare both files in plugin.json. When both are present, the Codex runtime prefers the MCP configuration for enterprise deployments and automatically falls back to the app connector for public store users. This allows a single plugin codebase to support both deployment models without modification.

Is .mcp.json required for all Codex plugins?

No. .mcp.json is only required for plugins that run on the Enterprise Store or need to communicate with private backends. Public ChatGPT store plugins only need .app.json to utilize OpenAI's managed connectors. Many plugins in the repository contain only the .app.json configuration.

What happens if neither .app.json nor .mcp.json is defined?

The plugin will fail to initialize. The Codex runtime requires at least one valid manifest reference in plugin.json to understand how to route API calls. Without either file, the system cannot determine whether to use a managed connector or a custom MCP server, resulting in a configuration error during deployment.

Do I need to host my own MCP server for the public ChatGPT store?

No. The public ChatGPT store exclusively uses the .app.json configuration and OpenAI-hosted connectors. You only need to provision and host your own MCP server when using .mcp.json for Enterprise Store deployments where you require custom routing, private network access, or specialized authentication flows that the standard connectors do not support.

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