How to Configure an MCP-Server Plugin for Claude: Complete Setup Guide

To configure an MCP-Server plugin for Claude, create a .mcp.json file at your repository root defining your server endpoints in an mcpServers map, then reference those server names in your skill code using functions from the Claude Plugin SDK.

The anthropics/claude-plugins-community repository demonstrates how backend-connected plugins use Model Context Protocol (MCP) servers to communicate with external services. When you configure an MCP-Server plugin for Claude, you establish a named endpoint that handles GraphQL operations for your skills without storing API tokens in your repository.

What Is an MCP-Server Configuration?

An MCP-Server (Model Context Protocol Server) acts as a connector between Claude and your backend service. According to the anthropics/claude-plugins-community source code, the configuration resides in a file named .mcp.json placed at the root of your plugin repository. When Claude Code loads your plugin, it reads this file to create named endpoints and manages authentication through an OAuth flow.

Step 1: Create the .mcp.json Configuration File

At the root of your plugin repository, create a file named .mcp.json. This file must contain a top-level object with an mcpServers property that maps server names to their connection details.

The following example from the tres-finance-plugin shows the required structure:

{
  "mcpServers": {
    "TRES Finance": {
      "type": "http",
      "url": "https://ai.tres.finance/mcp"
    }
  }
}

Source: tres-finance-plugin/.mcp.json

Step 2: Define Multiple Server Endpoints

You can define multiple MCP servers within the same configuration file to support different environments. Each entry requires a unique server name, a protocol type (http or https), and the endpoint URL.

{
  "mcpServers": {
    "My Company Backend": {
      "type": "https",
      "url": "https://api.mycompany.com/mcp"
    },
    "Staging": {
      "type": "http",
      "url": "http://staging.mycompany.com/mcp"
    }
  }
}

Step 3: Reference Servers in Skill Code

Skills communicate with MCP servers using the Claude Plugin SDK. Import build_query and execute from @anthropic/claude-plugin-sdk to construct and send GraphQL operations to your named server.

import { build_query, execute } from '@anthropic/claude-plugin-sdk';

// Build a GraphQL query
const query = build_query(`
  query GetUserInfo {
    viewer {
      id
      name
    }
  }
`);

// Execute against the named server
const result = await execute(query, { server: "My Company Backend" });

console.log(result.viewer);

The server parameter in the execute options object must match the key defined in your .mcp.json mcpServers map exactly.

Step 4: Install and Authenticate Your Plugin

Install your plugin in Claude Code using either the marketplace or local development commands. During first activation, Claude automatically opens a browser window to handle OAuth authentication with your MCP server.

Install from the marketplace:

/plugin marketplace add owner/repo-name

Install for local development:

claude --plugin-dir ./my-plugin

No API token storage is required in your repository source code, as Claude manages the authentication session after the initial OAuth handshake.

Step 5: Verify the MCP Connection

Test your configuration by running any skill that calls the MCP server. If the .mcp.json entry is malformed or the server is unreachable, Claude displays an authentication or connection error. Successful connections return the expected GraphQL response data directly in the conversation.

Summary

• Place .mcp.json at your repository root to define MCP server endpoints for Claude.
• Use the mcpServers map to name servers and specify their type (http or https) and url.
• Call servers in skills using execute() from the Claude Plugin SDK with the matching server name.
• Claude handles authentication via OAuth when the plugin is first enabled.
• Store plugin metadata in .claude-plugin/plugin.json alongside your MCP configuration.

Frequently Asked Questions

Where should I place the .mcp.json file in my repository?

Place the .mcp.json file at the root directory of your plugin repository. Claude Code scans for this file immediately when loading the plugin to parse the mcpServers configuration and establish the named endpoints for GraphQL communication.

Do I need to include API tokens in my plugin code when using an MCP server?

No. Claude plugins using MCP servers do not require API tokens in the repository source code. When you first enable the plugin, Claude opens a browser window to initiate an OAuth flow, and Claude manages the authentication session securely without exposing credentials in your codebase.

How do I reference different environments in my skill code?

Define multiple entries in the mcpServers map within .mcp.json (such as "Production" and "Staging"), then pass the specific server name as the server option in the execute() function from the Claude Plugin SDK. This allows the same skill logic to target different backends by changing only the server reference.

What file contains the plugin metadata alongside the MCP configuration?

The file .claude-plugin/plugin.json contains your plugin's metadata including the name, description, and skill list. While the .mcp.json file handles backend connectivity, the plugin.json in the .claude-plugin/ directory defines how Claude presents and categorizes your plugin in the interface.

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