MCP Server Configuration Format and Authentication in Claude Plugins

The MCP server configuration uses a JSON schema defined in .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 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 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 <token> header.

{
  "auth": {
    "type": "bearer",
    "tokenEnv": "MCP_TRES_FINANCE_TOKEN"
  }
}

In 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 <base64> header from these values.

{
  "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 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 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 to enable the TRES Finance plugin with secure token-based authentication:

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

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

{
  "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 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 and related skill documentation emphasize that proper environment configuration is required for authentication to succeed.

Summary

• .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 and testdino/.mcp.json

Frequently Asked Questions

Where should .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) 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.

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