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

MCP server plugins use centralized GraphQL tool servers declared in .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 Configuration File

An MCP server plugin ships a .mcp.json file that declares one or more MCP servers. As seen in the TRES Finance plugin at 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

{
  "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 demonstrates this pattern:

## 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:

{
  "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 file. These plugins do not require an .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, this skill contains no MCP references:

## Example: Running a CLI command

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

Claude issues a direct command-style tool call:

{
  "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	Individual skills invoking any API or Claude tool
Configuration file	.mcp.json	None (only plugin.json and 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 — plugin metadata (name, description, version)
• .mcp.json — MCP server declaration with URL and tool list
• skills/tres-report-create/SKILL.md — skill that uses execute tool for GraphQL queries
• 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.

Quickdesign: Pure Skill-Based Plugin

The quickdesign plugin contains no .mcp.json file. Its structure includes only:

• .claude-plugin/plugin.json
• skills/quickdesign/SKILL.md — direct CLI invocation

Similarly, the testdino plugin at 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 file in the .claude-plugin/ directory. Example from tres-finance-plugin/.claude-plugin/plugin.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 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 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 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.

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 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 files provide templates for this conversion.

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