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

Define MCP servers in your Claude plugin by declaring them in .claude-plugin/plugin.json under the mcpServers object, then reference the server ID in each skill's 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. 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:

{
  "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 file that specifies the MCP server in a dedicated section:

## 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 and 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:

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 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 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 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 points to a valid MCP-enabled GraphQL endpoint, not a REST API or unrelated service.

Summary

• Define once in .claude-plugin/plugin.json under mcpServers with unique IDs, URLs, and optional bearer token environment variables.

• Reference consistently in each skill's 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 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 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 file references a server ID that does not exist in .claude-plugin/plugin.json, the runtime returns an "MCP server not found" error and halts execution, preventing undefined behavior or failed network requests.

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