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

> Learn to configure MCP-based plugins in Claude Code using mcp.json. Define external service endpoints for Claude to invoke by name for seamless integration.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-08

---

**MCP-based plugins in Claude Code are configured by placing a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/41-validate-aux-files.sh) ensures that any present [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files contain valid JSON syntax before they are processed.

## Structure of the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) Schema

The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file, mixing transport types as needed for your plugin's architecture.

**HTTP Server Example:**

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

```

**Multiple Servers with Mixed Transports:**

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files and injects the `mcpServers` object into the plugin's primary manifest at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/41-validate-aux-files.sh) before merging into [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file?

Place [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) at the root of your plugin directory for primary definitions. You may optionally place an additional [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.