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

The .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 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 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, 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, plugins describe workflows using generic categories rather than specific product IDs. The root README.md emphasizes this flexibility: "Edit .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 at the plugin root directory when the 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, 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:

{
  "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 file defines servers with authentication and category metadata:

{
  "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:

{
  "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 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 example. This approach ensures the same plugin package works across teams using different infrastructure stacks.

Summary

• .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
• 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 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 resides at the plugin root, you can specify alternative files in 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 file defines the plugin's metadata, skills, and optional custom manifest paths, while .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 may reference the .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 and CONNECTORS.md documentation, you only need to edit the .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.

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