How the Tres Finance Plugin Integrates MCP Tools with Claude Code Skills: A Deep Dive

The Tres Finance plugin integrates MCP tools with Claude Code skills by declaring an MCP server in its plugin manifest and referencing built-in MCP tools (execute, introspect, validate_query, memory, get_viewer) within skill definitions written in Markdown.

The tres-finance-plugin in the anthropics/claude-plugins-community repository demonstrates a clean architecture pattern for extending Claude Code with external GraphQL services. This article examines how the plugin bridges Claude Code's skill system with Model Context Protocol (MCP) tooling to enable blockchain accounting workflows without embedding any network client code.

Plugin Manifest: Declaring the MCP Server Connection

Every Claude Code plugin begins with a manifest file. In tres-finance-plugin/.claude-plugin/plugin.json, the plugin declares its dependency on the TRES Finance MCP server and specifies required user configuration.

{
  "name": "tres-finance-plugin",
  "userConfig": {
    "DEBANK_API_KEY": {
      "title": "DeBank API Key",
      "description": "API key for DeBank Pro API access",
      "type": "string",
      "required": true
    }
  },
  "mcpServers": [
    {
      "name": "tres-mcp",
      "url": "https://ai.tres.finance/mcp"
    }
  ]
}

When Claude Code loads this plugin, it automatically creates an MCP connector named user-tres-finance. This connector handles authentication, knows the server URL and GraphQL schema, and exposes the MCP tools that skills can invoke. The plugin author never writes HTTP client code—Claude Code's runtime manages all networking concerns including retries and rate limiting.

Skill Definitions: Embedding MCP Tool Calls in Markdown

Skills are executable plans written as Markdown files under tres-finance-plugin/skills/. Each SKILL.md file contains natural language instructions that Claude Code parses into an execution pipeline, with embedded references to MCP tools.

Consider the Report Create skill in [tres-finance-plugin/skills/tres-report-create/SKILL.md](./tres-finance-plugin/skills/tres-report-create/SKILL.md). The skill describes a multi-step workflow where MCP tools appear as inline commands:

## Step 0: Organization Context

First, call `get_viewer` to obtain the current organization and user context.

## Step 1: Build the Query

For a Transaction Ledger report, construct a GraphQL query. If the report type is unfamiliar, run `introspect("transaction")` to discover exact argument names and types.

## Step 2: Validate Before Executing

Before running any mutation, use `validate_query` to check the assembled query against the live schema. This catches type mismatches early without triggering costly operations.

## Step 3: Execute and Poll

Run the query with `execute`. Verify the report row exists by querying `report(name: ...)`. Poll repeatedly with `execute` until status is `DONE` or `ERROR`.

These tool references—get_viewer, introspect, validate_query, execute, and memory—are built-in Claude Code primitives that automatically route to the configured MCP server.

Runtime Execution Flow

When a user invokes a skill, Claude Code translates the Markdown workflow into actual MCP operations. Here's the complete pipeline for creating a Transaction Ledger report:

Discovery with get_viewer

The skill first establishes context by calling the get_viewer tool, a simple MCP query that returns organization and user information.

Schema Introspection with introspect

If the requested report type is new, the skill calls introspect(<query>) to fetch argument signatures from the MCP server's GraphQL schema dynamically.

Query Validation with validate_query

Before executing mutations, the skill runs validate_query(<assembled query>). This sanity check prevents runtime errors by verifying types and structures against the live schema.

Core Execution with execute

The primary action uses execute to send GraphQL mutations. Here's the pattern from the skill definition:

# Assembled by Claude Code from the skill instructions

query = """
query($exportFormat: String, $exportName: String, $currency: String,
      $outputFormat: ReportOutputFormat, $timestamp_Gte: DateTime,
      $timestamp_Lte: DateTime) {
  transaction(exportFormat: $exportFormat, exportName: $exportName,
              currency: $currency, outputFormat: $outputFormat,
              timestamp_Gte: $timestamp_Gte, timestamp_Lte: $timestamp_Lte) {
    results { id }
  }
}
"""
variables = {
    "exportFormat": "BASIC_RAW_TRANSACTIONS",
    "exportName": "Transaction Ledger Q1 2025",
    "currency": "usd",
    "outputFormat": "CSV",
    "timestamp_Gte": "2025-01-01T00:00:00Z",
    "timestamp_Lte": "2025-03-31T23:59:59Z",
}
result = execute(query, variables)  # MCP tool call

The MCP server returns either a standard GraphQL response with errors: null or an error payload with error and error_type fields.

Verification and Polling

Because the MCP may return HTTP 200 without actually creating rows, the skill implements defensive verification:

# Verify the report exists

verify_query = """
query($name: String, $ordering: String, $limit: Int) {
  report(name: $name, ordering: $ordering, limit: $limit) {
    results { id name status }
  }
}
"""
verify_vars = {"name": "Transaction Ledger Q1 2025", "ordering": "-created_at", "limit": 1}
status = execute(verify_query, verify_vars)

# Poll until completion

while attempts < 10:
    status = execute(poll_query, poll_vars)
    if status["results"][0]["status"] == "DONE":
        download_link = status["results"][0]["link"]
        break
    sleep(60)
    attempts += 1

Result Presentation

Finally, the skill formats the presigned download URL as a clickable Markdown link:

[Click here to download your Transaction Ledger (CSV)](https://tres.finance/download/...)

For additional analysis, the skill may fetch the CSV via standard Python requests calls.

Architecture Benefits

The MCP-aware architecture of the tres-finance-plugin provides several advantages:

• Zero networking code: Skills contain no HTTP clients, authentication logic, or retry handlers
• Runtime portability: The same SKILL.md works across browser, desktop, and CI environments
• Automatic tooling: Claude Code handles MCP connector lifecycle, secret injection, and error propagation
• Extensibility: New GraphQL endpoints require only new Markdown skills, not code changes

Key Files in the Repository

File	Purpose
.claude-plugin/plugin.json	Declares plugin metadata, MCP server URL, and required secrets
skills/tres-report-create/SKILL.md	Complete MCP tool workflow with validation and polling
skills/tres-report-advisor/SKILL.md	Pre-execution advisory skill demonstrating conditional MCP usage
README.md	Plugin overview and MCP connection documentation

Summary

The tres-finance-plugin integrates MCP tools with Claude Code skills through three architectural layers:

• Manifest layer: Declares the tres-mcp server and DEBANK_API_KEY configuration in plugin.json
• Skill layer: References MCP tools (execute, introspect, validate_query, memory, get_viewer) within Markdown skill definitions
• Runtime layer: Delegates all network operations to Claude Code's built-in MCP connector, enabling portable, zero-code client implementations

This pattern—manifest → MCP connector → skill markdown → runtime tool calls—lets Claude Code perform complex blockchain accounting operations while the plugin author focuses solely on workflow logic.

Frequently Asked Questions

What MCP tools does the Tres Finance plugin use?

The plugin uses five built-in Claude Code MCP tools: execute for running GraphQL queries and mutations, introspect for dynamic schema discovery, validate_query for pre-execution type checking, memory for persisting working state, and get_viewer for fetching organization context. These tools are referenced by name in SKILL.md files and automatically routed to the configured MCP server.

Where is the MCP server URL configured?

The MCP server URL (https://ai.tres.finance/mcp) is declared in .claude-plugin/plugin.json under the mcpServers array. Claude Code reads this at plugin load time and establishes the user-tres-finance connector. Users never manually configure the endpoint—they only supply the DEBANK_API_KEY secret when prompted.

Can skills handle MCP server errors?

Yes. Skills explicitly handle GraphQL error responses by checking for error and error_type fields in the execute result. The Report Create skill also implements defensive patterns like verification queries and polling loops to handle cases where the MCP returns HTTP 200 without confirming data persistence.

How do I add a new skill to this plugin?

Create a new SKILL.md file under skills/<skill-name>/ and reference the same MCP tools. Define your workflow in natural language with embedded tool calls like `execute`. No code changes are required—Claude Code parses the Markdown and generates the appropriate MCP calls at runtime.

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