How Claude Plugins Integrate with MCP Servers: A Complete Technical Guide

Claude plugins integrate with MCP servers through a runtime GraphQL bridge that uses five built‑in MCP tools—get_viewer, introspect, build_query, execute, and memory—to discover schemas, build queries, and execute operations against remote MCP endpoints.

Each plugin skill in the anthropics/claude-plugins-community repository declares a compatibility requirement that binds it to a specific MCP connector. For example, TRES Finance skills specify "Requires TRES Finance MCP connector" in their metadata. At runtime, Claude invokes the MCP server's GraphQL API through a standardized JSON‑RPC‑style protocol, enabling dynamic, schema‑driven interactions without hard‑coded field lists or enums.

The Five Core MCP Tools for Claude Plugin Integration

Claude plugins rely on a consistent set of MCP tools to communicate with external services. Understanding each tool's role is essential for building robust integrations.

get_viewer – Confirm Connectivity and Org Context

The get_viewer tool establishes the initial handshake with the MCP server. It returns the authenticated organization context, confirming that the connector is alive and properly configured.

This tool is typically called first in any skill workflow. In [tres-wallets-upload/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md) (line 12), the documentation emphasizes: "Always fetch the ParentPlatform enum values live from the TRES MCP schema"—a step that follows the initial get_viewer or introspect call.

introspect – Discover the Live GraphQL Schema

Rather than hard‑coding GraphQL types or enum values, Claude plugins use introspect to pull the complete, up‑to‑date schema from the MCP server at runtime.

In [tres-settings-management/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-settings-management/SKILL.md) (line 53), the skill instructs Claude to "use the MCP introspect tool to discover available fields." This pattern prevents breakage when the remote API evolves and enables adaptive query construction.

build_query – Construct Valid GraphQL Operations

The build_query tool assists in generating syntactically correct GraphQL queries based on the introspected schema. While skills can hand‑craft queries, build_query provides a structured alternative when dynamic query generation is required.

Skills typically use this after introspect when they need to assemble complex queries with runtime‑determined fields or filters.

execute – Send Queries and Mutations to the MCP Server

The execute tool is the workhorse of Claude MCP integration. It transmits GraphQL queries and mutations to the MCP server endpoint (e.g., https://ai.tres.finance/mcp) and returns the response.

Two canonical examples from the TRES Finance plugin:

• [tres-report-create/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-report-create/SKILL.md) (line 16): "Trigger the export (GraphQL via MCP execute)"
• [tres-asc845-swap-reprice-skill/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-asc845-swap-reprice-skill/SKILL.md) (line 30): "All GraphQL calls use the user-tres-finance MCP server (execute tool)"

memory – Persist Query Recipes and Feedback

The memory tool enables skills to store reusable query patterns or submit structured feedback back to the MCP platform. This supports iterative improvement and user‑driven skill enhancement.

In [tres-request-skill-update/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-request-skill-update/SKILL.md) (line 23), the skill documents: "save it via the save_ai_conversation_feedback TRES MCP tool"—demonstrating how plugin feedback loops close through MCP.

The Claude Plugin MCP Integration Flow: Step by Step

Based on the anthropics/claude-plugins-community source code, all MCP‑integrated skills follow a predictable six‑step sequence:

Step 1: Discover Organization and Schema

Claude first confirms connectivity and retrieves the live schema. This eliminates enum hard‑coding and ensures the skill works against the current API version.

Step 2: Build the GraphQL Query

Using schema introspection data, the skill constructs a valid query—either through build_query or manual assembly with verified field names.

Step 3: Execute via MCP execute Tool

The query ships to the MCP server through the execute tool. The payload follows JSON‑RPC conventions, returning either a result or an error envelope.

Step 4: Unwrap and Handle Results

Skills must parse the response carefully. The test harness in [tres-report-create/tests/run_report_matrix.py](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-report-create/tests/run_report_matrix.py) (line 143) demonstrates: "Unwrap {result: …} and surface the MCP's error/error_type failure."

Step 5: Mutate or Act on Data

For write operations, skills issue additional execute calls with mutation documents. Examples include:

• updateBatchInternalAccounts – wallet management ([tres-wallets-upload/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md), line 227)
• createManualTransactionWithSubTransactions – ledger entries ([tres-explorer-tx-to-ledger/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-explorer-tx-to-ledger/SKILL.md), line 225)

Step 6: Store Memory or Collect Feedback

Final steps may persist reusable query recipes via memory or submit user feedback through dedicated MCP endpoints.

Complete Code Example: MCP Integration Pattern

The following Python pattern, derived from multiple TRES Finance skills, illustrates the standard MCP interaction sequence:

# 1️⃣ Get the viewer (org) – confirms MCP connectivity

viewer = await mcptool.get_viewer()   # MCP tool `get_viewer`

# 2️⃣ Introspect the schema (optional but recommended)

schema = await mcptool.introspect()  # MCP tool `introspect`

# 3️⃣ Build a GraphQL query (could be handcrafted)

query = """
query GetReport($type: String!, $format: String!) {
  exportReport(reportType: $type, format: $format) {
    status
    link
  }
}
"""

# 4️⃣ Execute the query via the MCP server

result = await mcptool.execute(query, variables={"type": "Ledger", "format": "CSV"})

# result is a dict like {"result": {...}} or {"error": "..."}.

# 5️⃣ Unwrap and handle errors

if "error" in result:
    raise RuntimeError(f"MCP error: {result['error']}")
report = result["result"]["data"]["exportReport"]
if report["status"] != "DONE":
    # poll or inform the user

    pass

# 6️⃣ Return the presigned link to the user

return report["link"]

This same structure appears across tres-report-create, tres-wallets-upload, and tres-asc845-swap-reprice-skill, confirming it as the canonical integration pattern.

Key Implementation Files in the Claude Plugins Community Repository

Skill	Primary Purpose	MCP Integration Highlight
tres-report-create/SKILL.md	Generate TRES Finance reports	execute-based export, polling logic, error unwrapping
tres-wallets-upload/SKILL.md	Wallet onboarding and account updates	introspect for ParentPlatform enum, updateBatchInternalAccounts mutation
tres-settings-management/SKILL.md	Organization and platform settings	Dynamic schema discovery with introspect and build_query
tres-asc845-swap-reprice-skill/SKILL.md	ASC 845 swap repricing	execute mutations with preview handling
tres-request-skill-update/SKILL.md	Plugin feedback submission	save_ai_conversation_feedback MCP endpoint
tres-tx-story/SKILL.md	Blockchain transaction analysis	execute queries against TRES Finance MCP
tres-report-create/tests/run_report_matrix.py	Integration test harness	Minimal MCP JSON‑RPC client with protocol version handling

Error Handling and Edge Cases in Claude MCP Integration

Robust error handling distinguishes production‑ready plugins. The source code reveals several critical patterns:

• Always check for error or error_type fields at the top level of execute responses before accessing result.data.
• Poll for asynchronous operations—report generation and batch updates may return PENDING status requiring follow‑up execute calls.
• Validate enum values live—never assume ParentPlatform or similar enums are static; re‑introspect when cached schemas expire.

The test file tests/run_report_matrix.py (line 143) encodes these expectations explicitly, making it a reference implementation for handling MCP failure modes.

Summary

• MCP integration is declarative: Each skill declares its required MCP connector in a compatibility line.
• Five tools enable all interactions: get_viewer, introspect, build_query, execute, and memory form the complete MCP surface.
• Runtime schema discovery eliminates brittleness: Skills introspect GraphQL schemas rather than hard‑coding field lists.
• execute is the primary workhorse: All queries and mutations route through this single MCP tool.
• Error handling follows JSON‑RPC conventions: Check error/error_type, unwrap result, and poll when necessary.

Frequently Asked Questions

What does MCP stand for in Claude plugins?

MCP stands for Model Connector Platform. It is Anthropic's standardized bridge that allows Claude plugins to communicate with external services through a unified GraphQL‑based protocol, abstracting vendor‑specific APIs behind a consistent interface.

How does a Claude plugin declare which MCP server it requires?

Each skill includes a compatibility declaration in its metadata—typically a line stating "Requires [Service] MCP connector." This declaration binds the skill to a specific MCP implementation at runtime. Claude uses this to route MCP tool calls to the correct endpoint.

Can Claude plugins work without an MCP server?

No. MCP‑dependent skills explicitly require their designated connector to function. The skills are designed around dynamic schema discovery and execute-based operations that assume an active MCP server. Without the connector, the skill cannot authenticate, introspect schemas, or perform remote operations.

What happens if the MCP server returns an error?

Skills must handle errors by inspecting the error or error_type fields in the execute response envelope. The canonical pattern, demonstrated in tres-report-create/tests/run_report_matrix.py, unwraps the result, checks for failure indicators, and either surfaces the error to the user or implements retry/polling logic for transient failures.

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