# MCP Server Configuration Format and Authentication in Claude Plugins > Learn the MCP server configuration format using JSON schema for GraphQL endpoints. Secure your Claude plugin skills with Bearer or Basic authentication and server selection. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: how-to-guide - Published: 2026-09-13 --- **The MCP server configuration uses a JSON schema defined in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files that specify GraphQL endpoints, support Bearer or Basic authentication via environment variables, and enable server selection for Claude plugin skills.** The `anthropics/claude-plugins-community` repository implements a standardized **MCP (Claude-Code Plugin) server configuration format** to manage connections between Claude AI agents and external GraphQL APIs. This configuration system relies on [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files that live either at the repository root or inside individual plugin folders, enabling secure credential management through environment variables while providing declarative endpoint definitions for plugin skills. ## Configuration File Structure The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file follows a strict schema that defines available servers, default routing behavior, and global environment mappings. According to the source code, the root object accepts three primary properties. ### Server Definitions The `servers` array contains one or more server objects, each specifying connection details: - **`name`**: Human-readable identifier used by skills to reference the server (e.g., `"tres-finance"`) - **`url`**: Base URL of the GraphQL endpoint (e.g., `"https://ai.tres.finance/mcp"`) - **`auth`**: Authentication object defining credential retrieval method - **`headers`** (optional): Static key-value pairs added to every HTTP request ### Optional Global Settings - **`defaultServer`**: String matching a server `name` that serves as the fallback when skills do not explicitly specify a target - **`environment`**: Object mapping environment variable names to values, useful for sharing secrets across multiple server definitions ## Authentication Methods The MCP runtime supports two authentication patterns defined in the `auth` object. Credentials are never hardcoded in JSON files; instead, the configuration references environment variable names that the runtime resolves at execution time. ### Bearer Token Authentication (Recommended) The Bearer token pattern is the primary authentication method used across the repository. The runtime reads the specified environment variable and injects it as an `Authorization: Bearer ` header. ```json { "auth": { "type": "bearer", "tokenEnv": "MCP_TRES_FINANCE_TOKEN" } } ``` In [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json), this pattern connects skills to the TRES Finance production API, with the runtime reading `MCP_TRES_FINANCE_TOKEN` from the host environment. ### Basic Authentication For legacy endpoints, the configuration supports Basic auth by specifying separate environment variables for username and password. The runtime constructs the standard `Authorization: Basic ` header from these values. ```json { "auth": { "type": "basic", "usernameEnv": "MCP_BASIC_USER", "passwordEnv": "MCP_BASIC_PASS" } } ``` ## Runtime Integration and Skill Usage When a Claude plugin skill invokes an MCP tool such as `execute`, `introspect`, or `get_viewer`, the runtime performs a lookup sequence defined in the source code: 1. Locates the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file in the plugin directory or repository root 2. Resolves the target server by name from the `servers` array (or uses `defaultServer` if no name is specified) 3. Retrieves authentication credentials from the environment variables defined in the `auth` object 4. Constructs the HTTP request with appropriate headers and sends it to the configured `url` Skills reference servers by name in their definitions. For example, [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md) documents that the skill expects an MCP configuration containing a server named `"tres-finance"` to handle GraphQL calls. ## Complete Configuration Examples ### Single Server Production Setup Place this configuration at [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json) to enable the TRES Finance plugin with secure token-based authentication: ```json { "defaultServer": "tres-finance", "servers": [ { "name": "tres-finance", "url": "https://ai.tres.finance/mcp", "auth": { "type": "bearer", "tokenEnv": "MCP_TRES_FINANCE_TOKEN" } } ] } ``` ### Multi-Environment Configuration Define multiple servers to support production and sandbox environments within the same plugin: ```json { "defaultServer": "tres-finance", "servers": [ { "name": "tres-finance", "url": "https://ai.tres.finance/mcp", "auth": { "type": "bearer", "tokenEnv": "MCP_TRES_FINANCE_TOKEN" } }, { "name": "tres-sandbox", "url": "https://sandbox.tres.finance/mcp", "auth": { "type": "bearer", "tokenEnv": "MCP_TRES_SANDBOX_TOKEN" } } ] } ``` Skills can target the sandbox explicitly by specifying `"server": "tres-sandbox"` in their MCP tool invocation, while others use the default production endpoint. ### Legacy Basic Authentication For endpoints requiring Basic auth, use this pattern found in [`testdino/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.mcp.json): ```json { "servers": [ { "name": "legacy-api", "url": "https://legacy.example.com/mcp", "auth": { "type": "basic", "usernameEnv": "LEGACY_USER", "passwordEnv": "LEGACY_PASS" }, "headers": { "X-Custom-Header": "value" } } ] } ``` ## Security Best Practices The MCP configuration format enforces security by design through environment variable indirection. **Never store token values or passwords directly in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files.** Instead, inject secrets through the host environment—whether in CI runners, local development containers, or deployment platforms. This approach keeps credentials out of source control while maintaining accessibility for the Claude AI agent. The [`tres-finance-plugin/skills/tres-erp-rule-suggestions/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-erp-rule-suggestions/SKILL.md) and related skill documentation emphasize that proper environment configuration is required for authentication to succeed. ## Summary - **[`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json)** files define MCP servers at the repository root or plugin level using a JSON schema with `servers`, `defaultServer`, and optional `environment` properties - Each server requires a `name`, `url`, and `auth` object, with optional static `headers` - **Bearer token** authentication uses `tokenEnv` to reference an environment variable containing the secret - **Basic authentication** uses `usernameEnv` and `passwordEnv` to construct Base64-encoded credentials - Skills reference servers by name (or rely on `defaultServer`) when invoking MCP tools like `execute` or `introspect` - The `anthropics/claude-plugins-community` repository demonstrates these patterns in [`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) ## Frequently Asked Questions ### Where should [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files be located? Configuration files can reside at the repository root for global server definitions or inside individual plugin folders (e.g., [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json)) for plugin-specific endpoints. The MCP runtime searches the plugin directory first, then falls back to the repository root when resolving server configurations. ### What authentication types are supported by the MCP configuration? The schema supports two authentication types: **Bearer** (using `tokenEnv` for the secret) and **Basic** (using `usernameEnv` and `passwordEnv`). Both methods retrieve credentials from environment variables at runtime rather than storing them in the JSON file. ### How do I configure multiple MCP servers for different environments? Define multiple objects in the `servers` array, each with a unique `name` (such as `"tres-finance"` and `"tres-sandbox"`). Set `defaultServer` to the production name for automatic fallback, or explicitly specify the server name in skill definitions to target staging or sandbox environments. ### Can I add custom HTTP headers to all MCP requests? Yes. Include a `headers` object within any server definition to apply static headers to every request. For example, `"headers": { "X-API-Version": "v2" }` ensures that header accompanies all GraphQL calls to that endpoint.