# How to Define MCP Servers for a Claude Plugin: Complete Configuration Guide

> Learn how to define MCP servers for your Claude plugin. Configure plugin.json and reference server IDs in SKILL.md for seamless integration. Complete configuration guide.

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

---

**Define MCP servers in your Claude plugin by declaring them in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) under the `mcpServers` object, then reference the server ID in each skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file using the `## MCP Server` heading.**

Claude plugins extend AI capabilities by connecting to external GraphQL endpoints through Managed Content Provider (MCP) protocols. In the `anthropics/claude-plugins-community` repository, MCP server definitions live in the plugin manifest while individual skills declare which server they utilize through standardized documentation headers.

## What Are MCP Servers in Claude Plugins?

MCP servers provide structured GraphQL interfaces that Claude plugins query using built-in tools like `execute`, `introspect`, and `build_query`. Rather than hardcoding endpoints directly in skill logic, the plugin architecture separates server configuration from implementation, enabling portable, secure integrations across different environments.

## The Plugin Manifest Structure

All MCP server definitions reside in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json). This central manifest acts as the single source of truth for external service connectivity.

### The mcpServers Configuration Object

The `mcpServers` top-level key contains a dictionary of server configurations. Each entry requires a unique identifier, endpoint URL, and optional authentication parameters:

```json
{
  "name": "tres-finance-plugin",
  "mcpServers": {
    "user-tres-finance": {
      "url": "https://ai.tres.finance/mcp",
      "description": "TRES Finance GraphQL MCP endpoint",
      "auth": {
        "type": "bearer",
        "tokenEnv": "TRES_MCP_TOKEN"
      }
    }
  }
}

```

**Key configuration fields:**

- **Server ID** (`user-tres-finance`): The unique identifier referenced by skills throughout the plugin.
- **url**: The GraphQL endpoint accepting MCP protocol requests.
- **auth.type**: Currently supports `bearer` for token-based authentication.
- **auth.tokenEnv**: The environment variable name containing the secret token.

The Claude runtime automatically injects session tokens for connected MCP servers, eliminating the need to manually handle credentials in skill code.

## Referencing MCP Servers in Skills

After defining servers in the manifest, individual skills must declare which MCP server they utilize through a standardized documentation pattern.

### The SKILL.md Convention

Each skill directory contains a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file that specifies the MCP server in a dedicated section:

```markdown

## MCP Server

All calls use the **user-tres-finance** MCP server (`execute` tool).

```

This declaration appears in files like [`tres-finance-plugin/skills/tres-tx-story/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-tx-story/SKILL.md) and [`tres-finance-plugin/skills/tres-import-contacts/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-import-contacts/SKILL.md). The runtime parses this heading to validate that the referenced server ID exists in the manifest before executing any GraphQL operations.

When implementing skill logic, developers invoke the server using the identifier:

```python
result = await execute(
    server="user-tres-finance",
    query=my_graphql_query,
    variables=payload
)

```

## Step-by-Step Implementation

Follow this sequence to add MCP connectivity to your Claude plugin:

1. **Edit the manifest**: Open [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and add a new entry under `mcpServers` with a unique identifier and endpoint URL.
2. **Configure authentication**: If the endpoint requires tokens, add the `auth` object with `type: "bearer"` and specify the environment variable in `tokenEnv`.
3. **Document in skills**: Create or edit [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files to include the `## MCP Server` section mentioning the server ID.

4. **Implement calls**: Use the `execute` tool with the `server` parameter set to your defined ID when making GraphQL requests.
5. **Validate connectivity**: Ensure the runtime can reach the endpoint and that the environment variable (if used) is set in the deployment environment.

## Authentication and Security Patterns

The plugin architecture enforces security by separating secrets from source code. Bearer tokens are never committed to the repository; instead, the manifest references environment variables through `tokenEnv`. The Claude runtime reads these variables at execution time, injecting them into MCP requests automatically.

For public or session-based MCP servers, omit the `auth` block entirely. The runtime handles session negotiation transparently when the server ID is properly declared in the manifest.

## Common Configuration Errors

Avoid these frequent mistakes when defining MCP servers:

- **Mismatched server IDs**: If [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) references `user-tres-finance` but the manifest defines `tres-finance-user`, the runtime throws a "MCP server not found" error during skill execution.
- **Hardcoded URLs in skills**: Never embed endpoint URLs directly in skill Python code or prompts. Always reference the server ID so that environment-specific URLs can be swapped via the manifest.
- **Missing environment variables**: When using `auth.tokenEnv`, ensure the variable is set in the deployment environment. Undefined variables cause authentication failures without explicit error messages in the skill logic.
- **Protocol mismatches**: Verify that the URL in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) points to a valid MCP-enabled GraphQL endpoint, not a REST API or unrelated service.

## Summary

- **Define once** in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) under `mcpServers` with unique IDs, URLs, and optional bearer token environment variables.
- **Reference consistently** in each skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) using the `## MCP Server` heading to declare which server handles GraphQL operations.

- **Call securely** using the `execute` tool with the `server` parameter; the runtime handles authentication injection automatically.
- **Avoid hardcoding** endpoint URLs or credentials in skill implementation files to maintain portability across development and production environments.

## Frequently Asked Questions

### Where exactly do I declare MCP servers in a Claude plugin?

MCP servers are declared in the [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file at the repository root under the `mcpServers` key. Each server requires a unique identifier, endpoint URL, and optional authentication configuration referencing environment variables.

### Can a single Claude plugin use multiple MCP servers?

Yes. The `mcpServers` object in the manifest supports multiple entries with unique identifiers. Each skill can reference a different server in its [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file, or multiple skills can share the same server ID. The runtime validates each connection independently before executing GraphQL operations.

### How does authentication work with MCP servers?

Authentication is configured in the manifest's `auth` block using `type: "bearer"` and `tokenEnv` to specify an environment variable name. The Claude runtime reads this variable at execution time and injects the bearer token into requests automatically. This prevents sensitive tokens from appearing in source code or version control.

### What happens if a skill references an undefined MCP server?

The Claude runtime performs validation before executing any skill. If a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file references a server ID that does not exist in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json), the runtime returns an "MCP server not found" error and halts execution, preventing undefined behavior or failed network requests.