How to Automate MCP Configurations for OpenAI Plugins

Yes, MCP configurations can be fully automated by programmatically generating .mcp.json files based on agent YAML definitions and a central registry of server endpoints.

The OpenAI Plugins repository leverages the Model Context Protocol (MCP) to enable tool-calling capabilities across plugins. Each plugin maintains an MCP configuration in a .mcp.json file at its root directory, defining HTTP endpoints or local command-line tools. Automating these configurations eliminates manual errors and ensures consistency across development and production environments.

Understanding the MCP Configuration Structure

MCP configurations in the openai/plugins repository follow a declarative JSON schema that maps server names to connection details.

The .mcp.json File Format

Each plugin’s .mcp.json file contains an mcpServers object that defines one or more server configurations. For example, the Cloudflare plugin at plugins/cloudflare/.mcp.json defines an HTTP-based MCP server:

{
  "mcpServers": {
    "cloudflare-api": {
      "type": "http",
      "url": "https://mcp.cloudflare.com/mcp",
      "note": "Official Cloudflare API MCP server. Uses OAuth on first connection, with optional bearer-token auth for automation."
    }
  }
}

In contrast, the build-iOS-apps plugin at plugins/build-ios-apps/.mcp.json demonstrates a command-line MCP server configuration:

{
  "mcpServers": {
    "xcodebuildmcp": {
      "type": "command",
      "command": "xcodebuildmcp",
      "args": []
    }
  }
}

The openai-developers plugin similarly uses a local MCP server configuration at plugins/openai-developers/.mcp.json, supporting both HTTP and command types according to the repository's implementation.

Automation Workflow for MCP Configurations

Automating MCP configurations involves scanning agent definitions, resolving server endpoints from a registry, and generating JSON files. This process is idempotent and can be integrated into CI/CD pipelines.

Step 1: Discover MCP References in Agent Files

Each skill requiring a remote service declares an MCP server reference in its agent YAML files located in plugins/<name>/agents/*.yaml. These references typically appear in fields like short_description or default_prompt. For example, the Cloudflare plugin references servers in files like plugins/cloudflare/skills/web-perf/agents/openai.yaml. A Python script can scan these YAML files to extract required server names using regex patterns or structured parsing.

Step 2: Resolve Endpoints from a Central Registry

Maintain a central registry file (e.g., mcp-registry.yaml) that maps server names to their configuration details including type, url, and authentication methods. This separates environment-specific URLs from plugin logic and allows bulk updates when endpoints change.

Step 3: Generate .mcp.json Files Programmatically

Using the discovered server names and registry mappings, generate the .mcp.json file for each plugin. This step overwrites existing configurations, making the automation repeatable. After generation, the plugin must be reloaded in Codex or the runtime environment to pick up changes.

Implementation Examples

The following examples demonstrate how to implement MCP configuration automation in different environments.

Python Script for Bulk Generation

This Python utility scans agent YAML files, queries a central registry, and writes .mcp.json files for all plugins:

import json
import pathlib
import yaml
import re

ROOT = pathlib.Path(__file__).parent
REGISTRY = ROOT / "mcp-registry.yaml"

# Load central registry mapping server names to configurations

with REGISTRY.open() as f:
    registry = yaml.safe_load(f)

def find_mcp_names(plugin_dir):
    """Return set of MCP server names referenced in agent YAML files."""
    names = set()
    for yaml_file in (plugin_dir / "agents").rglob("*.yaml"):
        with yaml_file.open() as f:
            data = yaml.safe_load(f)
            # Extract server references from descriptions

            match = re.search(r"\b(\w+-api)\b", data.get("short_description", ""))
            if match:
                names.add(match.group(1))
    return names

def generate_mcp_json(plugin_dir, names):
    """Write .mcp.json file for the plugin."""
    mcp_conf = {"mcpServers": {}}
    for name in names:
        if name not in registry:
            raise KeyError(f"Server {name!r} not in registry")
        mcp_conf["mcpServers"][name] = registry[name]
    (plugin_dir / ".mcp.json").write_text(json.dumps(mcp_conf, indent=2))

def main():
    for plugin in (ROOT / "plugins").iterdir():
        if not plugin.is_dir():
            continue
        names = find_mcp_names(plugin)
        if names:
            generate_mcp_json(plugin, names)
            print(f"Generated .mcp.json for {plugin.name}")

if __name__ == "__main__":
    main()

GitHub Actions CI Integration

Automate configuration updates in your Continuous Integration pipeline using GitHub Actions:

- name: Auto-generate MCP configs
  run: |
    python scripts/generate-mcp.py
    
- name: Commit updated configs
  uses: stefanzweifel/git-auto-commit-action@v4
  with:
    commit_message: "chore: update .mcp.json files"
    file_pattern: "**/.mcp.json"

Node.js Utility for Single Plugin Updates

For targeted updates or JavaScript-based toolchains, use this Node.js script to modify specific plugin configurations:

import { readFileSync, writeFileSync } from "fs";
import path from "path";

const plugin = process.argv[2];
const cfgPath = path.join("plugins", plugin, ".mcp.json");
const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));

cfg.mcpServers["my-custom-api"] = {
  type: "http",
  url: "https://api.example.com/mcp",
  note: "Custom API auto-generated"
};

writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
console.log(`Updated ${cfgPath}`);

Summary

• MCP configurations in the OpenAI Plugins repository are stored in .mcp.json files at the root of each plugin directory, defining HTTP or command-line servers.
• Automation is achieved by scanning agents/*.yaml files for server references, resolving details from a central registry, and generating JSON files programmatically.
• Key source files include plugins/cloudflare/.mcp.json for HTTP examples and plugins/build-ios-apps/.mcp.json for command-line examples.
• CI/CD integration ensures configurations remain synchronized across environments and automatically updates when agent definitions or server endpoints change.
• Reload requirement: After updating .mcp.json files, plugins must be reloaded in the Codex environment to activate new configurations.

Frequently Asked Questions

What is the format of an MCP configuration file?

An MCP configuration file uses the .mcp.json extension and contains a top-level mcpServers object. Each key represents a server name mapped to an object with type (either http or command), url or command path, and optional authentication or note fields. The Cloudflare plugin at plugins/cloudflare/.mcp.json demonstrates the HTTP format, while plugins/build-ios-apps/.mcp.json shows the command-line structure.

Can I use local command-line tools as MCP servers?

Yes, the MCP specification supports command-line tools through the type: "command" configuration. The build-iOS-apps plugin implements this pattern in plugins/build-ios-apps/.mcp.json by referencing the xcodebuildmcp binary. This allows plugins to execute local utilities while maintaining the same declarative configuration approach as HTTP endpoints.

How do I reload a plugin after updating its MCP configuration?

After modifying a .mcp.json file, you must reload the plugin in your Codex or OpenAI Plugins runtime environment. According to the repository documentation, the runtime does not hot-reload MCP configurations automatically. A reload can be triggered through the Codex interface or by restarting the local development server, ensuring the new server definitions are available for agent tool-calling.

Where are MCP server references defined in the plugin structure?

MCP server references are typically declared within agent YAML files located in the plugins/<plugin-name>/agents/ directory. These files may reference server names in fields like short_description or default_prompt. For instance, the Cloudflare plugin defines agents in paths like plugins/cloudflare/skills/web-perf/agents/openai.yaml. Automation scripts scan these YAML files to discover which MCP servers a plugin requires before generating the corresponding .mcp.json configuration.

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