# How to Automate MCP Configurations for OpenAI Plugins

> Automate MCP configurations for OpenAI plugins by programmatically generating mcp json files. Streamline your plugin deployment with this essential guide.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Yes, MCP configurations can be fully automated by programmatically generating [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file contains an `mcpServers` object that defines one or more server configurations. For example, the Cloudflare plugin at [`plugins/cloudflare/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) defines an HTTP-based MCP server:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/build-ios-apps/.mcp.json) demonstrates a command-line MCP server configuration:

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

```

The `openai-developers` plugin similarly uses a local MCP server configuration at [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) files for all plugins:

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

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

```javascript
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) for HTTP examples and [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/.mcp.json) demonstrates the HTTP format, while [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) configuration.