How to Version Control MCP Configurations for OpenAI Plugins

MCP (Model Context Protocol) configurations for OpenAI plugins can be fully version controlled because they are stored as standard JSON files (.mcp.json) directly within each plugin's repository, enabling Git tracking, pull request reviews, and CI/CD automation.

The openai/plugins repository treats AI tool integrations as first-class source code by embedding MCP server definitions directly in plugin directories. Since these configurations live as plain .mcp.json files alongside application code, they inherit all the benefits of Git version control. This approach allows development teams to track changes to AI agent capabilities with the same rigor applied to critical infrastructure.

Where MCP Configurations Live in the Repository

In the openai/plugins codebase, each plugin maintains its own MCP client definitions in dedicated JSON files at the plugin root level. For example, the plugins/openai-developers/.mcp.json file contains a complete MCP server description committed directly to version control. Similarly, the Cloudflare plugin stores its configuration at plugins/cloudflare/.mcp.json, demonstrating that multiple plugins can maintain independent, version-controlled MCP setups within the same monorepo.

These files define the mcpServers map, specifying command executables, arguments, and working directories required to launch MCP servers. Because the configuration resides in the file system rather than an external database or secret manager, Git naturally records every modification to server endpoints, command flags, and execution contexts.

Benefits of Version Controlling MCP Configurations

Tracking .mcp.json files in Git provides four critical advantages for AI plugin development:

• Traceability: Every change to an MCP server definition is logged in commit history, allowing teams to revert breaking configurations with standard Git commands.
• Collaborative Review: Pull requests capture exactly which endpoints, command strings, or arguments are being added or altered, enabling security-focused code review of AI tool integrations.
• Environment Consistency: The same .mcp.json exists on every repository clone, guaranteeing identical MCP client behavior across development, staging, and production environments.
• Pipeline Automation: CI/CD systems can validate JSON schema, lint command strings, or run integration tests against defined MCP servers during automated builds.

Implementation Workflow for Version-Controlled MCP

Follow this workflow to manage MCP configurations as code in the openai/plugins repository:

1. Modify Configuration: Update the .mcp.json file in your plugin directory (e.g., plugins/your-plugin/.mcp.json), adjusting the mcpServers entries, commands, or arguments.

2. Commit Changes: Stage and commit the file using standard Git commands:

   git add plugins/your-plugin/.mcp.json
   git commit -m "Add MCP server configuration for deployment tools"

3. Review via Pull Request: Open a pull request so teammates can review security implications of new command or args entries before merging.

4. Automated Validation: Configure CI to test the MCP configuration. The pipeline can copy the committed .mcp.json into the build environment and verify the server starts correctly using the MCP client library.

5. Deploy: Merge the configuration to main, where it becomes part of the canonical plugin version deployed to production.

Code Examples for MCP Version Control

Basic Local MCP Server Configuration

The following .mcp.json structure matches the configuration found in plugins/openai-developers/.mcp.json, defining a local Node.js MCP server:

{
  "mcpServers": {
    "my-local-mcp": {
      "cwd": ".",
      "command": "node",
      "args": [
        "./mcp/server.mjs"
      ]
    }
  }
}

This file is committed to the repository, ensuring all team members use the same server execution parameters.

Generating Configurations with Vercel CLI

According to the Vercel CLI skill documentation in plugins/vercel/skills/vercel-cli/SKILL.md, you can generate MCP configurations programmatically:

# Link local MCP client config to a Vercel project

vercel mcp --project my-awesome-project

This command updates the local .mcp.json or ~/.cursor/mcp.json with Vercel MCP endpoint details, enabling AI agents to call tools like list_deployments without manual token handling. Once generated, these files can be committed to version control.

Loading Version-Controlled Configurations in Code

As demonstrated in the AI SDK skill (plugins/vercel/skills/ai-sdk/SKILL.md), applications can consume these committed configurations:

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  // URL sourced from the version-controlled .mcp.json
  url: "http://localhost:4000/mcp"
});

const tools = await client.tools();
await client.close();

Because the endpoint originates from a Git-tracked file, the same MCP server configuration propagates consistently across all environments.

Summary

• MCP configurations for OpenAI plugins are stored as .mcp.json files directly in plugin directories like plugins/openai-developers/ and plugins/cloudflare/.
• These JSON files can be fully version controlled using Git, enabling change tracking, pull request reviews, and automated testing.
• The Vercel CLI provides commands like vercel mcp to generate configurations that can be committed to the repository.
• Version-controlling MCP setups ensures traceability, collaborative security review, and environment consistency for AI agent capabilities.

Frequently Asked Questions

What file format are MCP configurations stored in?

MCP configurations are stored as standard JSON files named .mcp.json. These files contain a top-level mcpServers object that maps server names to their execution details, including command paths, arguments, and working directories. The plugins/openai-developers/.mcp.json file in the repository provides a concrete example of this structure.

Can I use the same MCP configuration across different environments?

Yes. Because .mcp.json files live in the repository, they are cloned identically to every development machine, CI runner, and deployment target. This ensures that AI agents use the same MCP server endpoints and execution parameters regardless of the environment, eliminating configuration drift between local and production systems.

How do I add a new MCP server to my OpenAI plugin?

Create or modify the .mcp.json file in your plugin directory (e.g., plugins/my-plugin/.mcp.json), add a new entry to the mcpServers object with the appropriate command and args fields, then commit the file to Git. The OpenAI developers plugin at plugins/openai-developers/.mcp.json provides a working reference implementation showing the exact JSON schema required.

Are there CLI tools to help generate MCP configurations?

Yes. The Vercel CLI provides a vercel mcp command that generates MCP client configurations for Vercel projects. As documented in plugins/vercel/skills/vercel-cli/SKILL.md, running vercel mcp --project <name> creates the necessary JSON entries that can then be committed to version control, streamlining the process of connecting AI agents to Vercel-hosted tools.

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