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

> Configure an MCP-Server plugin for Claude easily. Follow our setup guide to define endpoints in .mcp.json and reference them in your skill code for seamless integration.

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

---

**To configure an MCP-Server plugin for Claude, create a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) Configuration File

At the root of your plugin repository, create a file named [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

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

```

*Source: [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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.

```json
{
  "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.

```javascript
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```bash
/plugin marketplace add owner/repo-name

```

Install for local development:

```bash
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** alongside your MCP configuration.

## Frequently Asked Questions

### Where should I place the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file in my repository?

Place the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) contains your plugin's metadata including the name, description, and skill list. While the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file handles backend connectivity, the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) in the `.claude-plugin/` directory defines how Claude presents and categorizes your plugin in the interface.