How the OpenAI Plugins Marketplace Is Configured: A Technical Guide

The OpenAI plugins marketplace is configured through a central JSON manifest located at .agents/plugins/marketplace.json, which defines the marketplace ID, API endpoints, plugin discovery paths, and authentication settings.

The openai/plugins repository serves as the canonical source for the Codex and OpenAI plugin ecosystem. Understanding how the marketplace is configured centers on a declarative configuration system that automatically registers plugins and exposes them through unified APIs without requiring manual registration code.

The Central marketplace.json Configuration File

At the root of the repository, the file .agents/plugins/marketplace.json acts as the single source of truth for marketplace behavior. This JSON manifest supplies the core runtime parameters that power the plugin discovery system.

The marketplace loader reads this manifest on initialization to establish the foundational environment. According to the source structure, this file contains the essential metadata required to bootstrap the marketplace instance and configure how the system discovers and serves individual plugins.

Key Marketplace Configuration Settings

The manifest defines several critical configuration keys that control marketplace operations:

marketplaceId and apiBaseUrl

The marketplaceId field provides a unique identifier for the marketplace instance, enabling distinction between different deployment environments. The apiBaseUrl setting establishes the root path for all marketplace API calls, typically configured as /api/marketplace or similar endpoint prefixes.

pluginDirectory and Discovery Paths

The pluginDirectory field specifies the relative path where the system scans for individual plugin definitions. By default, the loader searches the plugins/ folder for valid descriptor files. The configuration supports multiple plugin definition formats, primarily looking for .app.json files within plugin subdirectories or alternatively .codex-plugin/plugin.json for Codex-specific implementations.

Authentication and Routing

The auth section contains optional authentication parameters, including API key requirements or OAuth scope definitions. The routingMap defines the URL mapping structure that connects marketplace routes to specific plugin handlers, while the metadata block stores human-readable information such as the marketplace name, description, and version string.

How Plugin Discovery Works

When the repository initializes, the marketplace loader processes the manifest and automatically registers every valid plugin found under the configured directory. Each plugin must contain a descriptor file—either plugins/<plugin-name>/.app.json or plugins/<plugin-name>/.codex-plugin/plugin.json—that the loader validates against the marketplace schema.

This declarative approach enables automatic plugin inclusion without additional registration code. Developers simply add a valid JSON descriptor to the appropriate subdirectory, and the marketplace configuration handles the rest, exposing the plugin through GraphQL and REST APIs for consumption by Codex, Claude, and other LLM clients.

Programmatic Access to Marketplace Configuration

You can programmatically inspect the marketplace configuration by fetching and parsing the manifest directly:

import json
import urllib.request

# Load the marketplace manifest from the repository

url = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json"
with urllib.request.urlopen(url) as resp:
    marketplace = json.load(resp)

# Access core configuration values

api_base = marketplace["apiBaseUrl"]
marketplace_id = marketplace["marketplaceId"]

print(f"Marketplace ID: {marketplace_id}")
print(f"API Base URL: {api_base}")

# Construct endpoint for plugin listing

plugins_endpoint = f"{api_base}/plugins"

This pattern allows client applications to dynamically adapt to marketplace specifications without hardcoding endpoint values.

Summary

• The .agents/plugins/marketplace.json file serves as the central configuration manifest for the entire OpenAI plugins marketplace.
• Key settings include marketplaceId for unique identification, apiBaseUrl for endpoint routing, and pluginDirectory for discovery paths.
• Plugins are automatically discovered through plugins/*/.app.json or plugins/*/.codex-plugin/plugin.json descriptors.
• The configuration supports optional auth parameters and a routingMap for handler mapping.
• No manual registration code is required; the marketplace loader processes the manifest and registers plugins automatically.

Frequently Asked Questions

What file format does the OpenAI plugins marketplace use for configuration?

The marketplace uses a JSON-based manifest system. The primary configuration resides in .agents/plugins/marketplace.json, while individual plugin definitions use .app.json or .codex-plugin/plugin.json formats within their respective plugin directories.

Where does the marketplace look for plugin definitions?

According to the source configuration, the marketplace scans the relative path specified by the pluginDirectory setting (typically plugins/) for descriptor files. It searches for .app.json files directly in plugin subdirectories or plugin.json files within .codex-plugin/ subfolders.

Can the marketplace configuration include authentication requirements?

Yes. The manifest supports an optional auth field that can specify API keys, OAuth scopes, or other security parameters. This allows the marketplace to enforce authentication standards across all registered plugins or specific plugin categories.

How do I add a new plugin to the OpenAI marketplace?

Create a new subdirectory under plugins/ and add a valid .app.json descriptor file containing your plugin's metadata, endpoints, and schema definitions. The marketplace loader automatically discovers and registers the plugin on the next initialization cycle without requiring changes to the core marketplace configuration.

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