# What Is the .mcp.json File? Connector Manifest Configuration for Claude Plugins

> Discover the purpose of the .mcp.json file. This connector manifest defines MCP server access for Claude plugins, enabling dynamic tool resolution and avoiding hard-coded details.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: how-to-guide
- Published: 2026-06-01

---

**The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file serves as the connector manifest that declares which Multi-Connector Protocol (MCP) servers a Claude plugin can access, enabling dynamic tool resolution without hard-coding vendor-specific details.**

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file sits at the heart of the **anthropics/knowledge-work-plugins** ecosystem, acting as the single source of truth for external tool connections. This JSON configuration decouples plugin logic from specific service implementations, allowing Claude to discover and invoke tools dynamically across categories like CRM, video conferencing, and storage.

## Core Purpose and Architecture

### Connector Manifest for MCP Servers

At its core, the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file contains a top-level `"mcpServers"` object that maps server identifiers to their connection details. Each entry specifies the **URL**, **authentication method**, and **category hints** that Claude uses to route tool calls.

As noted in [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md), the file "pre-configures specific MCP servers, but any MCP server in that category works" [grep†/CONNECTORS.md†L7-L9]. This means a plugin requesting a `"crm"` category tool can work with any MCP-compatible CRM service listed in the manifest, whether Salesforce, HubSpot, or a custom internal solution.

### Enabling Tool-Agnostic Plugins

By externalizing server definitions into [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json), plugins describe workflows using generic categories rather than specific product IDs. The root [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) emphasizes this flexibility: "Edit [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) to point at your specific tool stack" [grep†/README.md†L71-L73]. This architecture allows the same plugin codebase to function across development, staging, and production environments without code changes.

## File Location and Configuration Conventions

### Default Location at Plugin Root

Claude automatically looks for [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) at the plugin root directory when the [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) manifest does not specify a custom path. According to the cowork-plugin-customizer reference documentation, if the `mcpServers` field is omitted from [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json), Claude falls back to this default location [grep†/cowork-plugin-customizer/references/mcp-servers.md†L68-L70].

### Custom Path Configuration

Plugin authors can override the default location by specifying a custom path in [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json):

```json
{
  "name": "Finance Plugin",
  "description": "Enterprise finance tools",
  "mcpServers": "${CLAUDE_PLUGIN_ROOT}/custom-mcp.json"
}

```

This pattern, documented in the cowork-plugin-management skills reference, supports environment-specific deployments by allowing users to substitute different manifest files at runtime [grep†/cowork-plugin-customizer/references/mcp-servers.md†L16-L20].

## Practical Configuration Examples

### Basic Structure

A minimal [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file defines servers with authentication and category metadata:

```json
{
  "mcpServers": {
    "zoomServer": {
      "url": "https://zoom.mcp.example.com",
      "auth": {
        "type": "apiKey",
        "key": "<YOUR_ZOOM_API_KEY>"
      },
      "categories": ["video_conference"]
    }
  }
}

```

### Adding Multiple Servers

Extend the manifest by adding entries to the `mcpServers` object:

```json
{
  "mcpServers": {
    "zoomServer": {
      "url": "https://zoom.mcp.example.com",
      "auth": { "type": "apiKey", "key": "<ZOOM_KEY>" },
      "categories": ["video_conference"]
    },
    "salesforceServer": {
      "url": "https://salesforce.mcp.mycorp.com",
      "auth": {
        "type": "oauth",
        "clientId": "<CLIENT_ID>",
        "clientSecret": "<CLIENT_SECRET>"
      },
      "categories": ["crm"]
    }
  }
}

```

After saving, any skill requesting a `"crm"` connector automatically routes to the new Salesforce endpoint.

### Per-Environment Overrides

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file supports local modifications without touching plugin code. Users can edit the root-level file to point at internal tools or test instances, as implemented in the [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json) example. This approach ensures the same plugin package works across teams using different infrastructure stacks.

## Summary

- **[`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)** is the connector manifest that declares available MCP servers for Claude plugins according to the knowledge-work-plugins source code
- The file uses a top-level `"mcpServers"` object containing URLs, authentication details, and capability categories
- Claude resolves tool calls by matching requested categories against servers listed in this manifest
- Default location is the plugin root, overridden via the `mcpServers` field in [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json)
- Environment-specific deployments require only file edits, not code changes, supporting dev/staging/prod workflows

## Frequently Asked Questions

### What does MCP stand for in .mcp.json?

MCP stands for **Multi-Connector Protocol**, the standardized protocol that Claude uses to communicate with external tool servers. The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file acts as the registry of these protocol endpoints, telling Claude which servers are available for tool invocation.

### Can I use multiple .mcp.json files for different environments?

Yes. While the default [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) resides at the plugin root, you can specify alternative files in [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) using environment variables or relative paths like `${CLAUDE_PLUGIN_ROOT}/custom-mcp.json`. This allows different server configurations for development, staging, and production without rebuilding the plugin.

### How does .mcp.json differ from plugin.json?

The [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) file defines the plugin's metadata, skills, and optional custom manifest paths, while [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) contains only the connector definitions—the actual server endpoints and credentials that Claude uses to execute tool calls at runtime. The [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) may reference the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file via the `mcpServers` field, but they serve distinct purposes.

### Do I need to modify plugin code to switch MCP servers?

No. According to the repository's [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) and [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) documentation, you only need to edit the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file to point at different servers within the same category. Claude dynamically resolves the appropriate endpoint based on the category hints in the manifest, making the plugins truly tool-agnostic.