# How Are MCP Servers Configured for Claude Plugins?

> Discover how Claude plugins configure MCP servers using the .mcp.json manifest. Learn to map server identifiers to endpoints and bearer tokens for seamless integration.

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

---

**Claude plugins configure MCP servers through a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) Manifest File

Every plugin that interacts with an MCP backend must include a **[`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json) – Configures the TRES Finance MCP server
- [`testdino/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.mcp.json) – Configures the TestDino MCP server

## Structure of the `mcpServers` Object

The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file contains a single top-level key, **`mcpServers`**, whose value is an object mapping arbitrary server names to their configuration objects.

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

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

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file handles server connectivity, high-level plugin metadata resides in **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) defines the plugin's structure, while [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) provides the runtime wiring to external MCP services.

## Summary

- **[`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json) and [`testdino/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.