# Skill implementation automatically uses the App Connector

> Learn the difference between .app.json and .mcp.json for Codex plugins. Automatically implement skills with App Connector for ChatGPT & Enterprise Store integrations.

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

---

#.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json)** file, typically located at `plugins/<plugin>/.codex-plugin/plugin.json`. This manifest declares which integration files are available:

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

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

```python

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

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

```python

# 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`](https://github.com/openai/plugins/blob/main/plugins/linear/.app.json))
- **`plugins/<plugin-name>/.mcp.json`** — Enterprise MCP server descriptor (e.g., [`plugins/linear/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/linear/.mcp.json))
- **`plugins/<plugin>/.codex-plugin/plugin.json`** — Top-level plugin definition that references the manifests
- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** — Root documentation explaining the architectural distinction between app connectors and MCP servers

## Summary

- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** configures **public-store, managed connectors**—the default zero-maintenance integration for the ChatGPT store
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) to utilize OpenAI's managed connectors. Many plugins in the repository contain only the [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) configuration and OpenAI-hosted connectors. You only need to provision and host your own MCP server when using [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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.