How to Configure MCP with .mcp.json for External Tool Integration

To configure MCP with .mcp.json, create the file at your plugin root, set the mcpServers property to point to your server manifest, define each server’s url, auth, and tools configuration, reference the file in your plugin.json, and validate the setup before completing authentication.

The openai/plugins repository uses the Multipurpose Control Protocol (MCP) to connect Codex agents with external tools. Configuring MCP requires a .mcp.json file that declares how the plugin communicates with external tool servers. This guide walks through the exact steps to configure MCP with .mcp.json for external tool integration, based on the reference implementations found in the OpenAI Developers and Supabase plugins.

Create the .mcp.json File at the Repository Root

Place the .mcp.json file at the top-level directory of your plugin. For example, the OpenAI Developers plugin stores its configuration at plugins/openai-developers/.mcp.json. This file serves as the primary manifest that tells the Codex runtime where to locate external tool servers.

Declare the MCP Server URLs

Inside .mcp.json, populate the mcpServers property with a path that points to a JSON manifest describing each MCP server. You can use a relative path such as "./.mcp.json" for self-reference or an absolute URL like "https://mcp.supabase.com/mcp" for external hosted manifests.

{
  "mcpServers": "./.mcp.json"
}

Define the Server Manifest

Within the same file (or a referenced external file), list each server under a servers key. For each server, you must provide the endpoint details, authentication method, and available tools.

{
  "servers": [
    {
      "name": "Supabase",
      "url": "https://mcp.supabase.com/mcp",
      "auth": {
        "type": "oauth2",
        "authorizationUrl": "https://supabase.com/auth",
        "tokenUrl": "https://supabase.com/token"
      },
      "tools": [
        {
          "name": "fetchTable",
          "description": "Retrieve rows from a Supabase table",
          "input_schema": {
            "type": "object",
            "properties": {
              "table": { "type": "string" },
              "limit": { "type": "integer" }
            },
            "required": ["table"]
          }
        }
      ]
    }
  ]
}

Required fields for each server:

• url: The base HTTP endpoint the Codex runtime contacts.
• auth: Authentication details, such as OAuth 2.1 flows or API-key headers.
• tools: An array of tool definitions including name, description, and JSON schema for inputs.

Reference the MCP Configuration in plugin.json

In your plugin’s descriptor file located at .codex-plugin/plugin.json, set the mcpServers property to point to your .mcp.json file. This ensures the Codex runtime loads the MCP configuration at startup.

{
  "mcpServers": "./.mcp.json"
}

The OpenAI Developers plugin demonstrates this pattern in its plugin.json at plugins/openai-developers/.codex-plugin/plugin.json.

Validate the Configuration and Authenticate

Run your plugin’s test suite (for example, npm test or the provided .mcp.json validator) to verify the JSON is well-formed and that server URLs are reachable.

If the server requires authentication, such as the OAuth 2.1 flow used by Supabase, trigger the authentication flow from the agent, complete it in your browser, and reload the session. The Supabase skill documentation at plugins/supabase/skills/supabase/SKILL.md explicitly instructs users to verify this configuration step.

Real-World Examples in the Repository

Several plugins in the openai/plugins repository demonstrate working configurations:

• OpenAI Developers: Contains a ready-made .mcp.json and references it in plugin.json at plugins/openai-developers/.mcp.json.
• Supabase: Documentation at plugins/supabase/skills/supabase/SKILL.md guides users to create a .mcp.json pointing to https://mcp.supabase.com/mcp.
• Daloopa: The README at plugins/daloopa/README.md mentions the requirement for a .mcp.json configuration for Codex integration.

Summary

• Place .mcp.json at the root of your plugin directory (e.g., plugins/your-plugin/.mcp.json).
• Set mcpServers to define the path to your server manifest, using relative paths or absolute URLs.
• Define server details under the servers key, including url, auth, and tools arrays.
• Reference the file in .codex-plugin/plugin.json using the mcpServers property.
• Validate the configuration with test suites and complete any required OAuth 2.1 authentication flows.

Frequently Asked Questions

What is the purpose of the .mcp.json file?

The .mcp.json file acts as a manifest that tells the Codex runtime how to connect to external tool servers via the Multipurpose Control Protocol. It defines server endpoints, authentication methods, and available tools that the plugin can invoke.

How do I reference an external MCP server URL?

Set the mcpServers property to an absolute URL such as "https://mcp.supabase.com/mcp" instead of a relative path. The runtime will fetch the manifest from that endpoint to discover available tools and authentication requirements.

Where should the .mcp.json file be located?

Place the file at the top-level directory of your plugin repository. For example, the OpenAI Developers plugin stores it at plugins/openai-developers/.mcp.json, and the Daloopa plugin references it in its root directory.

What authentication methods are supported in MCP configuration?

The auth field supports OAuth 2.1 flows (with authorizationUrl and tokenUrl) and API-key based authentication. The specific method depends on the external tool server requirements, as documented in the server’s manifest.

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