How MCP Server Integration Powers the Tres Finance Plugin: A Technical Deep Dive

The tres-finance plugin connects to the TRES MCP server at https://ai.tres.finance/mcp through Claude-provided MCP tools that wrap GraphQL operations over JSON-RPC, using four core functions—introspect, build_query, execute, and get_viewer—to enable secure, schema-driven financial data operations without hard-coded field names.

The anthropics/claude-plugins-community repository hosts the tres-finance plugin, which demonstrates a sophisticated MCP (Managed Communication Protocol) server integration pattern. This plugin leverages Claude's native MCP connector architecture to communicate with the TRES Finance GraphQL API, enabling dynamic schema discovery and type-safe query construction across multiple financial analysis skills.

MCP Server Architecture and Configuration

All tres-finance skills communicate through a single MCP server endpoint. The plugin expects a connector named user-tres-finance to be present in the Claude environment, as defined in .claude-plugin/marketplace.json.

The MCP server endpoint is unified across all skills:

https://ai.tres.finance/mcp

This endpoint handles JSON-RPC 2.0 requests over HTTP, requiring a bearer token for authentication and maintaining session state via the Mcp-Session-Id header. According to the skill descriptions in tres-finance-plugin/skills/tres-report-create/SKILL.md, this server acts as the exclusive gateway for all GraphQL operations.

The Four Core MCP Tools

The integration relies on four standardized tools provided by the MCP connector. These tools abstract the underlying HTTP transport while exposing a GraphQL-centric interface to the skills.

1. get_viewer

This tool identifies the current authenticated user and organization context. It returns viewer metadata required for scoping subsequent queries to the correct financial entity.

2. introspect

The introspect tool fetches the live GraphQL schema from the MCP server. Skills use this at runtime to discover available fields, enums, and query names rather than relying on static definitions. This ensures compatibility when the TRES API schema evolves.

3. build_query

This tool safely composes GraphQL queries from structured inputs. It accepts parameters for operation type (query or mutation), operation name, field selections, and variables, returning a validated query string.

4. execute

The execute tool sends built queries or mutations to the MCP server and returns the JSON response. It handles the JSON-RPC tools/call method, authentication headers, and error normalization.

Low-Level Client Implementation

For testing and debugging, the repository includes a lightweight JSON-RPC client in tres-finance-plugin/skills/tres-report-create/tests/run_report_matrix.py. This McpClient class demonstrates the wire protocol underlying the higher-level MCP tools.

from run_report_matrix import McpClient
import os

token = os.getenv("TRES_BEARER_TOKEN")
client = McpClient("https://ai.tres.finance/mcp", token)
init_info = client.initialize()  # → {'name': 'TRES MCP', 'version': '…'}

The client implements three critical mechanisms:

• Bearer Authentication: The token is injected into the Authorization header for all requests
• Session Management: Tracks the Mcp-Session-Id header across calls to maintain server-side state
• JSON-RPC Framing: Wraps requests in the standard JSON-RPC 2.0 envelope with method names like initialize and tools/call

This low-level implementation mirrors the behavior of Claude's built-in MCP tools, providing a reference for understanding the transport layer.

Typical Skill Execution Flow

Skills like tres-report-create follow a standardized five-step pattern when interacting with the MCP server. This flow leverages schema introspection to avoid hard-coding GraphQL field names.

Step 1: Schema Discovery

The skill calls introspect to fetch the live schema and identify available types, such as the availableReportTypes enum.

Step 2: Query Construction

Using build_query, the skill dynamically constructs a mutation or query based on user input. For example, triggering a report export:

export_mut = tools.build_query(
    operation="mutation",
    name="exportReport",
    input={"type": "LEDGER", "format": "CSV"},
    fields=["id"]
)

Step 3: Initial Execution

The skill invokes execute to run the mutation on the MCP server:

export_resp = tools.execute(query=export_mut, variables={})
report_id = export_resp["data"]["exportReport"]["id"]

Step 4: Polling for Completion

For long-running operations, the skill polls via the execute tool until the status indicates completion:

while True:
    poll_q = tools.build_query(
        operation="query",
        name="report",
        variables={"id": report_id},
        fields=["status", "downloadLink"]
    )
    poll_resp = tools.execute(query=poll_q, variables={"id": report_id})
    if poll_resp["data"]["report"]["status"] == "DONE":
        link = poll_resp["data"]["report"]["downloadLink"]
        break
    time.sleep(5)

Step 5: Result Delivery

Once the operation completes, the skill returns the presigned S3 download link or processed data to the user.

Schema-Driven Safety and Compatibility

The MCP integration enforces a schema-driven development pattern throughout the tres-finance plugin. Rather than embedding hard-coded GraphQL field names, skills rely entirely on runtime schema discovery via introspect and dynamic query construction via build_query.

This architectural decision ensures that when the TRES Finance GraphQL API evolves—adding new report types, fields, or mutations—the skills automatically adapt without requiring code changes or redeployment. The pattern is consistently documented across skill descriptions, including tres-tx-story/SKILL.md and tres-cost-basis/SKILL.md, which note that "All GraphQL calls use the TRES Finance MCP server."

Summary

• The tres-finance plugin uses a single MCP server endpoint at https://ai.tres.finance/mcp for all GraphQL operations
• Four core tools—get_viewer, introspect, build_query, and execute—handle authentication, schema discovery, query construction, and execution
• The test harness in run_report_matrix.py demonstrates the underlying JSON-RPC protocol with bearer token authentication and session management
• Skills follow a standardized flow: introspect schema, build query, execute, poll for completion, and return results
• Schema-driven design eliminates hard-coded field names, ensuring compatibility with evolving TRES Finance APIs

Frequently Asked Questions

What is the MCP connector name required for the tres-finance plugin?

The plugin expects a connector named user-tres-finance to be configured in the Claude environment. This connector supplies the four core MCP tools and is referenced in .claude-plugin/marketplace.json.

How does authentication work with the TRES MCP server?

The MCP server requires a bearer token passed in the Authorization header. According to the test harness in run_report_matrix.py, the client must also track the Mcp-Session-Id header across requests to maintain session continuity with the JSON-RPC endpoint.

Why do tres-finance skills use introspect instead of static GraphQL schemas?

The introspect tool enables runtime discovery of the GraphQL schema, allowing skills to discover available fields, enums, and operations dynamically. This ensures that skills remain compatible when the TRES Finance API evolves without requiring code updates or redeployment.

Can developers test MCP interactions outside of Claude?

Yes. The run_report_matrix.py file provides a standalone McpClient class that implements the JSON-RPC protocol used by the MCP server. Developers can use this low-level client to test authentication, query execution, and session management against the https://ai.tres.finance/mcp endpoint.

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