How to Configure MCP-Based Plugins Using `.mcp.json` in Claude Code

MCP-based plugins in Claude Code are configured by placing a .mcp.json file at the plugin root or under .claude-plugin/, where the mcpServers object defines external service endpoints that Claude can invoke by name.

The anthropics/claude-plugins-community repository uses the Managed Compute Protocol (MCP) to allow plugins to expose external services—ranging from HTTP APIs to local command-line processes—to Claude Code. This configuration is declarative, requiring no executable code within the configuration file itself, and is processed during the plugin scanning phase to populate the plugin manifest.

File Location and Discovery Order

The plugin scanner searches for MCP definitions in two specific locations within each plugin directory. According to the source code in .github/actions/scan-plugins/lib/pin-check.sh, the loader checks these paths in strict priority order:

1. <plugin-root>/.mcp.json
2. <plugin-root>/.claude-plugin/.mcp.json

If both files exist, their contents are merged, with the root-level file taking precedence in case of naming conflicts. If neither file is present, the plugin registers without any MCP server capabilities. The validation script .github/actions/validate-plugins/scripts/41-validate-aux-files.sh ensures that any present .mcp.json files contain valid JSON syntax before they are processed.

Structure of the .mcp.json Schema

The .mcp.json file contains a single top-level object with an mcpServers property. Each key within mcpServers represents a unique server instance that Claude can target.

{
  "mcpServers": {
    "Server-Name": {
      "type": "protocol-type",
      "url": "endpoint-or-command"
    }
  }
}

• Server-Name – A human-readable identifier used by Claude when invoking the server (e.g., "TRES Finance").
• type – The transport mechanism. Supported values include http for web endpoints and stdio for local command-line processes.
• url – For http servers, this is the base URL (e.g., https://ai.tres.finance/mcp). For stdio servers, this field contains the command string to execute (e.g., node ./agent.js).

Defining HTTP and Stdio MCP Servers

You can define multiple servers within a single .mcp.json file, mixing transport types as needed for your plugin's architecture.

HTTP Server Example:

{
  "mcpServers": {
    "TRES Finance": {
      "type": "http",
      "url": "https://ai.tres.finance/mcp"
    }
  }
}

Multiple Servers with Mixed Transports:

{
  "mcpServers": {
    "Local Agent": {
      "type": "stdio",
      "url": "node ./agent.js"
    },
    "Remote Service": {
      "type": "http",
      "url": "https://service.example.com/mcp"
    }
  }
}

Integration with the Plugin Manifest

During the scan-plugins action, the system reads the discovered .mcp.json files and injects the mcpServers object into the plugin's primary manifest at .claude-plugin/plugin.json. This merged manifest serves as the source of truth for both Claude Code and the CLI tooling.

When Claude encounters a command like /tres-finance-plugin:TRES Finance /list_accounts, the runtime resolves the server name "TRES Finance" to the corresponding URL defined in the manifest and forwards the request to the appropriate endpoint. The CLI commands (claude-plugin suite) also reference this merged configuration to launch or proxy requests to stdio-based servers.

Summary

• .mcp.json declares external service endpoints for Claude Code plugins using a static JSON structure.
• The file is discovered at the plugin root or under .claude-plugin/, with the root location taking precedence during merging.
• Each server requires a unique name, transport type (http or stdio), and endpoint URL or command string.
• Validation occurs in .github/actions/validate-plugins/scripts/41-validate-aux-files.sh before merging into .claude-plugin/plugin.json.
• Claude invokes configured servers using the syntax /plugin-name:Server-Name followed by the specific command.

Frequently Asked Questions

Where should I place the .mcp.json file?

Place .mcp.json at the root of your plugin directory for primary definitions. You may optionally place an additional .mcp.json inside .claude-plugin/ for secondary or override configurations. The scanner processes the root file first, then merges the subdirectory file.

What transport types are supported in .mcp.json?

The type field accepts http for RESTful endpoints and stdio for local command-line processes. HTTP servers require a full URL in the url field, while stdio servers specify an executable command string that the CLI will spawn as a subprocess.

How are multiple MCP servers handled?

You can define multiple servers within the single mcpServers object, each with a unique key name. During the scan phase, all defined servers are merged into the plugin manifest, making them simultaneously available to Claude. The server name serves as the unique identifier for routing requests.

How does Claude resolve server names to endpoints?

Claude uses the merged manifest generated during the scan-plugins action. When you invoke a server using the /plugin-name:Server-Name syntax, the runtime looks up "Server-Name" in the mcpServers object of the manifest, retrieves the associated url and type, and routes the request accordingly—either as an HTTP request to the specified URL or as a message to a spawned stdio process.

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