How Are MCP Servers Configured for Claude Plugins?

Claude plugins configure MCP servers through a .mcp.json manifest file located in the plugin root, which maps server identifiers to HTTP endpoints and optional environment-based bearer tokens.

In the anthropics/claude-plugins-community repository, each plugin declares its Model-Code-Protocol (MCP) connectivity via this JSON manifest. The configuration isolates server endpoints per plugin and injects authentication tokens at runtime without storing secrets in the repository.

The .mcp.json Manifest File

Every plugin that interacts with an MCP backend must include a .mcp.json file at its root directory. This file serves as the single source of truth for Claude to discover and authenticate to external MCP servers.

Key locations in the reference repository include:

• tres-finance-plugin/.mcp.json – Configures the TRES Finance MCP server
• testdino/.mcp.json – Configures the TestDino MCP server

Structure of the mcpServers Object

The .mcp.json file contains a single top-level key, mcpServers, whose value is an object mapping arbitrary server names to their configuration objects.

{
  "mcpServers": {
    "Server Name": {
      "url": "https://endpoint.example.com/mcp",
      "tokenEnv": "ENV_VAR_NAME",
      "defaultHeaders": {},
      "description": "Optional description"
    }
  }
}

Required Fields

Each server entry must specify:

• url – The HTTP/HTTPS endpoint hosting the MCP server. For example, the TRES Finance plugin declares "https://ai.tres.finance/mcp" according to the source configuration in tres-finance-plugin/.mcp.json.

Optional Authentication and Headers

• tokenEnv – The name of an environment variable containing the bearer token. When Claude executes MCP tools like execute, introspect, or get_viewer, the runtime reads this variable and injects the token into the request headers. The token value is never committed to the repository.
• defaultHeaders – A static object of headers to include with every request to this server.
• description – Human-readable text explaining the server's purpose.

Runtime Configuration Lookup

When a skill invokes an MCP tool, Claude performs the following steps:

1. Server Resolution – Identifies the server name from the skill's context.
2. Manifest Lookup – Retrieves the URL from the corresponding entry in .mcp.json.
3. Authentication Injection – If tokenEnv is defined, reads the specified environment variable and attaches the bearer token to the request.
4. Request Execution – Sends the HTTP request to the declared endpoint.

This process ensures that multiple plugins can declare different MCP servers without interference, maintaining strict isolation between plugin environments.

Configuration Examples

Single Server Configuration

The TRES Finance plugin demonstrates a minimal valid configuration:

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

Multiple Servers per Plugin

A plugin can declare multiple isolated backends by adding entries to the mcpServers map:

{
  "mcpServers": {
    "TRES Finance": {
      "url": "https://ai.tres.finance/mcp",
      "tokenEnv": "TRES_MCP_TOKEN"
    },
    "Internal Analytics": {
      "url": "https://custom.example.com/mcp",
      "tokenEnv": "CUSTOM_MCP_TOKEN",
      "description": "Internal analytics MCP"
    }
  }
}

Relationship to Plugin Metadata

While the .mcp.json file handles server connectivity, high-level plugin metadata resides in .claude-plugin/plugin.json. This separation allows the plugin manifest to describe capabilities and entry points without exposing endpoint URLs or authentication schemes. The files work together: plugin.json defines the plugin's structure, while .mcp.json provides the runtime wiring to external MCP services.

Summary

• .mcp.json must be placed at the root of the plugin directory and contain valid JSON.
• The mcpServers object maps server names to configuration objects with required url fields.
• Authentication uses the tokenEnv field to reference environment variables, keeping secrets out of version control.
• Claude isolates MCP configurations per plugin, preventing cross-plugin server interference.
• Files like tres-finance-plugin/.mcp.json and testdino/.mcp.json in the anthropics/claude-plugins-community repository demonstrate production patterns.

Frequently Asked Questions

What file format does Claude require for MCP server configuration?

Claude requires a JSON file named .mcp.json placed in the plugin root. The file must contain a top-level mcpServers object; YAML or other formats are not supported.

How does authentication work without storing tokens in the repository?

The tokenEnv field specifies the name of an environment variable that contains the bearer token. At runtime, Claude reads this variable from the execution environment and injects it into request headers, ensuring tokens never appear in source code.

Can one plugin connect to multiple MCP servers?

Yes. The mcpServers object accepts multiple entries, allowing a single plugin to interact with distinct backends simultaneously. Each server maintains independent configuration and authentication.

What happens if a skill calls an MCP tool but .mcp.json is missing?

If the manifest is absent or the requested server name is not defined in mcpServers, Claude will fail the tool invocation with an "MCP not configured" error, blocking execution until the configuration is provided.

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