# How to Configure MCP with .mcp.json for External Tool Integration > Learn how to configure MCP with .mcp.json for seamless external tool integration. Follow step-by-step instructions to connect your servers and define tools. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-07-04 --- **To configure MCP with [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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. ```json { "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. ```json { "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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), set the `mcpServers` property to point to your [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file. This ensures the Codex runtime loads the MCP configuration at startup. ```json { "mcpServers": "./.mcp.json" } ``` The OpenAI Developers plugin demonstrates this pattern in its [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) at [`plugins/openai-developers/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) and references it in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) at [`plugins/openai-developers/.mcp.json`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.mcp.json). - **Supabase**: Documentation at [`plugins/supabase/skills/supabase/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/supabase/skills/supabase/SKILL.md) guides users to create a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) pointing to `https://mcp.supabase.com/mcp`. - **Daloopa**: The README at [`plugins/daloopa/README.md`](https://github.com/openai/plugins/blob/main/plugins/daloopa/README.md) mentions the requirement for a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) configuration for Codex integration. ## Summary - **Place [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** at the root of your plugin directory (e.g., [`plugins/your-plugin/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.