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

> Discover how MCP server integration powers the Tres Finance plugin. Explore the technical deep dive into GraphQL, JSON-RPC, and core functions for secure financial data operations.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).

The **MCP server endpoint** is unified across all skills:

```text
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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.

```python
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:

```python
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:

```python
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:

```python
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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-tx-story/SKILL.md) and [`tres-cost-basis/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.