# MCP Server Plugins vs Skill-Based Plugins: A Technical Guide to the Claude Plugin Architecture

> Explore MCP server plugins versus skill-based plugins. Understand how MCP uses centralized GraphQL tool servers while skill-based plugins use individual API calls or local commands.

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

---

**MCP server plugins use centralized GraphQL tool servers declared in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json), while skill-based plugins rely on individual skill files that make direct API calls or run local commands.**

The `anthropics/claude-plugins-community` repository implements two distinct plugin paradigms for extending Claude's capabilities. Understanding the architectural differences between **MCP server plugins** and **skill-based plugins** is essential for developers building integrations with Claude's plugin system.

## What Are MCP Server Plugins?

MCP server plugins are a specialized plugin class where the core integration point is an **MCP (Claude Tool Server) endpoint**. These plugins expose a **GraphQL-style tool suite** through a declarative configuration rather than imperative skill code.

### The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) Configuration File

An MCP server plugin ships a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file that declares one or more MCP servers. As seen in the TRES Finance plugin at [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json), this configuration specifies:

- The **MCP server URL** (e.g., `https://ai.tres.finance/mcp`)
- The **available tools**: `execute`, `introspect`, `build_query`, `validate_query`, `get_viewer`, and others

```json
{
  "servers": [
    {
      "name": "tres-finance",
      "url": "https://ai.tres.finance/mcp",
      "tools": ["execute", "introspect", "build_query", "validate_query", "get_viewer"]
    }
  ]
}

```

When a skill runs within an MCP server plugin, it **does not make raw HTTP calls**. Instead, the skill instructs Claude to invoke MCP tools, and the MCP server handles **authentication**, **schema discovery**, and **query execution** on behalf of the skill.

### MCP Tool Execution Flow

The skill definition in [`tres-finance-plugin/skills/tres-report-create/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-report-create/SKILL.md) demonstrates this pattern:

```yaml

## Using the TRES MCP

- Validate the query with `validate_query` (optional)
- Run the GraphQL query with the MCP `execute` tool

```

Based on these instructions, Claude generates a tool call like:

```json
{
  "tool": "execute",
  "arguments": {
    "server": "tres-finance",
    "query": "query ExportReport($type:ReportType!,$format:ExportFormat!){exportReport(...)}",
    "variables": {"type":"TRANSACTION_LEDGER","format":"CSV"}
  }
}

```

The MCP server processes this request and returns a structured JSON payload. This design provides a **uniform, declarative interface** for any data source wrapped in an MCP server.

## What Are Skill-Based Plugins?

**Skill-based plugins** are collections of individual **skills**, each described in a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. These plugins **do not require** an [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file or MCP server declaration. The skill logic independently decides how to retrieve data—whether through REST APIs, CLI programs, or Claude's built-in tools.

### Direct Execution Without MCP

The `quickdesign` plugin illustrates this architecture. Located at [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), this skill contains no MCP references:

```yaml

## Example: Running a CLI command

- Run the `quickdesign` binary with arguments
- Return the generated video URL

```

Claude issues a direct command-style tool call:

```json
{
  "tool": "run",
  "arguments": {
    "command": "quickdesign upscale --input video.mp4 --output video_upscaled.mp4"
  }
}

```

**No MCP server is involved**—the skill handles its own I/O and external service interaction.

## Key Architectural Differences

| Aspect | MCP Server Plugin | Skill-Based Plugin |
|--------|-------------------|--------------------|
| **Primary integration point** | One or more MCP servers defined in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) | Individual skills invoking any API or Claude tool |
| **Configuration file** | [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) | None (only [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files) |
| **Data access pattern** | GraphQL queries/mutations through `execute` tool | Direct HTTP/CLI calls or Claude-native tools |
| **Schema handling** | Dynamic discovery via `introspect` / `build_query` | Usually hard-coded request/response shapes |
| **Authentication** | Handled centrally by MCP server | Implemented per-skill |
| **Runtime behavior** | Claude sends tool call to MCP server; server returns structured JSON | Claude runs skill code locally or fetches data via normal request |
| **Typical use case** | Enterprise-grade data platforms with GraphQL layers (e.g., TRES Finance) | Quick utilities, external services, or scripts without GraphQL requirements |

## Repository Examples

### TRES Finance: MCP Server Plugin

The `tres-finance-plugin` directory demonstrates the complete MCP server plugin structure:

- [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) — plugin metadata (name, description, version)
- [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) — MCP server declaration with URL and tool list
- [`skills/tres-report-create/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-report-create/SKILL.md) — skill that uses `execute` tool for GraphQL queries
- [`skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-wallets-upload/SKILL.md) — additional skill leveraging same MCP server

All skills in this plugin share the **centralized MCP infrastructure** defined in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json).

### Quickdesign: Pure Skill-Based Plugin

The `quickdesign` plugin contains **no [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file**. Its structure includes only:

- [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)
- [`skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/quickdesign/SKILL.md) — direct CLI invocation

Similarly, the `testdino` plugin at [`testdino/skills/testdino-sessions/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/skills/testdino-sessions/SKILL.md) follows the same skill-based pattern without MCP dependencies.

## When to Use Each Plugin Type

**Choose an MCP server plugin when:**
- Your data source exposes a **GraphQL API** that benefits from schema introspection
- You need **centralized authentication and request handling**
- Multiple skills share the **same backend infrastructure**
- You want **dynamic query building** without hard-coding field names

**Choose a skill-based plugin when:**
- You're integrating a **REST API or CLI tool** without GraphQL
- You need **fine-grained control** over request/response handling
- The integration is **simple enough** to not warrant server infrastructure
- You're building **quick prototypes or single-purpose utilities**

## Implementing Plugin Metadata

Both plugin types require a [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file in the `.claude-plugin/` directory. Example from [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json):

```json
{
  "name": "tres-finance",
  "version": "1.0.0",
  "description": "Access TRES Finance data through MCP server"
}

```

This metadata file is **orthogonal to the MCP vs skill distinction**—it simply registers the plugin with Claude's plugin system.

## Summary

- **MCP server plugins** provide a **centralized, schema-driven API layer** through [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) configuration, with skills delegating data operations to MCP tools like `execute` and `introspect`

- **Skill-based plugins** are **autonomous collections of skills** that directly implement their own data access patterns without MCP server intermediation

- The **presence of [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json)** is the definitive signal distinguishing MCP server plugins from skill-based alternatives in the `anthropics/claude-plugins-community` repository

- **TRES Finance** exemplifies the MCP pattern with its GraphQL tool server, while **quickdesign** and **testdino** demonstrate pure skill-based architectures

## Frequently Asked Questions

### Can a single plugin combine MCP server and skill-based approaches?

No. The repository structure indicates a clean architectural separation. A plugin either declares an [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file (making it an MCP server plugin) or does not (making it skill-based). Skills within an MCP plugin consistently use MCP tools rather than direct API calls.

### What tools must an MCP server implement?

According to the TRES Finance implementation, standard MCP tools include: `execute` for running GraphQL queries, `introspect` for schema discovery, `build_query` for assisted query construction, `validate_query` for pre-execution checking, and `get_viewer` for metadata retrieval. The specific tool set is declared per-server in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json).

### How does authentication work in MCP server plugins?

The MCP server handles authentication centrally. Skills never manage credentials directly; they simply invoke MCP tools, and the server authenticates requests to the underlying data source. This centralization reduces credential sprawl across multiple skills.

### Can I convert a skill-based plugin to use an MCP server?

Yes, but it requires structural changes: add an [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file, deploy or identify an MCP-compatible server for your data source, and rewrite skill instructions to use MCP tools instead of direct API calls. The TRES Finance plugin's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files provide templates for this conversion.