Agenticledger MCP TheTieCanton

The Tie Canton MCP Server

Overview

The Tie Canton MCP Server provides comprehensive access to Canton Network analytics and metrics through The Tie's V3 API. This Model Context Protocol (MCP) server enables AI agents to query Canton validator data, network metrics, reward distributions, leaderboards, and user activity statistics.

Key Features:

• 🔍 12 specialized tools for Canton network data
• 📊 Access to validators, rewards, and leaderboard data
• 📈 Network metrics including transactions and active users
• 🎯 Pagination support for large datasets
• ⚡ Type-safe with full Zod schema validation
• 🛡️ Comprehensive error handling

Authentication Pattern

Pattern: API Key (Direct)

This MCP server uses The Tie's API key authentication. Your API key should be provided directly as the accessToken parameter.

Token Format

{
  accessToken: "your-thetie-api-key"
}

How to get an API key:

1. Contact The Tie at api@thetie.io
2. Request access to Canton API endpoints
3. Receive your API key via email
4. Use the key in the accessToken field

Available Tools

1. get_cumulative_metrics

Description: Retrieve cumulative metrics data for the Canton network with pagination support. Results are ordered by round date in descending order.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response to get next page

Example:

{
  accessToken: "your-api-key",
  limit: 50,
  marker: "2024-01-15"
}

Response:

{
  "success": true,
  "data": {
    "status": "success",
    "code": 200,
    "metadata": {
      "timestamp": "2025-01-17T10:00:00Z",
      "version": "3.0",
      "pagination": {
        "limit": 50,
        "total": 150,
        "nextMarker": "2024-01-10",
        "prevMarker": null
      }
    },
    "data": [
      {
        "roundDate": "2024-01-15",
        "totalTransactions": 12345,
        "activeValidators": 42,
        "networkValue": 1000000
      }
    ]
  }
}

2. get_cumulative_validators

Description: Get cumulative validator data for Canton network. Returns historical data about validators including their performance metrics over time.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 25
}

3. get_highlight_metrics

Description: Retrieve key highlight metrics for Canton network. Provides important network statistics and KPIs.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• roundDate (string, optional): Specific round date to retrieve metrics for (YYYY-MM-DD format)

Example:

{
  accessToken: "your-api-key",
  roundDate: "2024-01-15"
}

4. get_holder_leaderboard

Description: Get Canton token holder leaderboard rankings. Shows top token holders with their balances.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 20
}

5. get_monthly_app_rewards

Description: Retrieve monthly application rewards data for Canton network. Shows reward distribution to applications.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• month (string, optional): Month to retrieve rewards for (YYYY-MM format)
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  month: "2024-01",
  limit: 30
}

6. get_reward_leaderboard

Description: Get Canton reward leaderboard showing top reward earners. Displays rankings of participants by total rewards earned.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 15
}

7. get_reward_split_by_role

Description: Get breakdown of rewards split by participant roles in Canton network. Shows how rewards are distributed across different role types.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• roundDate (string, optional): Specific round date to retrieve reward split for (YYYY-MM-DD format)

Example:

{
  accessToken: "your-api-key",
  roundDate: "2024-01-15"
}

8. get_top_applications_30d

Description: Get top Canton applications by activity over the last 30 days. Shows most active applications ranked by usage metrics.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 10
}

9. get_validator_leaderboard

Description: Get Canton validator leaderboard rankings. Shows top validators by performance metrics.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 25
}

10. get_transaction_count

Description: Get transaction count metrics for Canton network over a specified date range. Provides insights into network activity levels.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• startDate (string, optional): Start date for transaction count query (YYYY-MM-DD format)
• endDate (string, optional): End date for transaction count query (YYYY-MM-DD format)

Example:

{
  accessToken: "your-api-key",
  startDate: "2024-01-01",
  endDate: "2024-01-31"
}

11. get_daily_active_users

Description: Get daily active users metrics for Canton network over a specified date range. Shows network engagement and user activity trends.

Parameters:

• accessToken (string, required): The Tie API key for authentication
• startDate (string, optional): Start date for daily active users query (YYYY-MM-DD format)
• endDate (string, optional): End date for daily active users query (YYYY-MM-DD format)

Example:

{
  accessToken: "your-api-key",
  startDate: "2024-01-01",
  endDate: "2024-01-31"
}

12. get_cumulative_parties

Description: Get cumulative parties data for Canton network. Returns historical data about network participants (parties).

Parameters:

• accessToken (string, required): The Tie API key for authentication
• limit (number, optional): Number of records to return (default: 100, max: 1000)
• marker (string, optional): Pagination marker from previous response

Example:

{
  accessToken: "your-api-key",
  limit: 40
}

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• A valid API key from The Tie

Setup Steps

1. Clone or download this repository:

git clone https://github.com/oregpt/Agenticledger_MCP_TheTieCanton.git
cd Agenticledger_MCP_TheTieCanton

1. Install dependencies:

npm install

1. Build the TypeScript code:

npm run build

1. Configure your MCP client:

Add to your MCP settings configuration (e.g., Claude Desktop config):

{
  "mcpServers": {
    "thetie-canton": {
      "command": "node",
      "args": [
        "/absolute/path/to/TheTieCantonMCP/dist/index.js"
      ]
    }
  }
}

1. Restart your MCP client to load the server.

Testing

Run Integration Tests

Integration tests verify all 12 tools work with real API credentials.

1. Create test credentials file:

cp test-credentials.example.json test-credentials.json

1. Add your API key to test-credentials.json:

{
  "accessToken": "your-actual-thetie-api-key"
}

1. Run the tests:

npm run test:integration

The test suite will:

• Test all 12 API endpoints
• Display real-time results
• Show request/response data
• Generate a summary report
• Save detailed results to test-results.json

Expected output:

🚀 Starting Integration Tests for The Tie Canton MCP Server
═══════════════════════════════════════════════════════════

🧪 Testing: get_cumulative_metrics
📍 Endpoint: /v3/integrations/canton/cumulative-metrics
📋 Parameters: {"limit":10}
✅ SUCCESS (342ms)
...

📊 TEST SUMMARY
═══════════════════════════════════════════════════════════
Total Tests: 12
✅ Passed: 12
❌ Failed: 0
⏱️  Average Duration: 418.23ms

Development

Project Structure

TheTieCantonMCP/
├── src/
│   ├── index.ts                 # Main MCP server implementation
│   └── test-integration.ts      # Integration test suite
├── dist/                        # Compiled JavaScript (generated)
├── package.json                 # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── README.md                   # This file
├── ABILITIES_LIMITATIONS.md    # Capability documentation
├── PLATFORM_INTEGRATION_REPORT.md  # Testing evidence
└── test-credentials.example.json   # Example credentials

Build Commands

• npm run build - Compile TypeScript to JavaScript
• npm run watch - Watch mode for development
• npm test - Run test suite
• npm run test:integration - Run integration tests with real API

Platform Integration Notes

Response Format

All tools return standardized responses:

{
  success: boolean;
  data?: any;      // Present if success is true
  error?: string;  // Present if success is false
}

Error Handling

The server handles common error scenarios:

• 401 Unauthorized: Invalid or expired API key
• 403 Forbidden: API key lacks permission for endpoint
• 404 Not Found: Requested resource doesn't exist
• 429 Rate Limited: Too many requests, retry later
• 500+ Server Errors: The Tie API issues

Rate Limiting

The Tie API enforces rate limits. The server:

• Returns clear error messages when rate limited
• Suggests waiting before retrying
• Respects HTTP 429 responses

Best Practices

1. Cache responses when data doesn't change frequently (e.g., historical leaderboards)
2. Use pagination (limit parameter) for large datasets
3. Implement retry logic with exponential backoff for transient failures
4. Monitor API usage to stay within rate limits

Troubleshooting

"Invalid or expired API key"

• Verify your API key is correct in test-credentials.json
• Contact The Tie support (api@thetie.io) if your key has expired
• Ensure you have access to Canton endpoints

"Rate limit exceeded"

• Wait before making additional requests
• Implement request throttling in your application
• Contact The Tie to discuss rate limit increases

"Resource not found"

• Verify date parameters are in correct format (YYYY-MM-DD or YYYY-MM)
• Check that data exists for the requested time period
• Some historical data may have limited retention

Build Errors

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

API Documentation

For detailed API documentation, visit:

• Canton API Docs: https://api-thetie.io/v3/docs/canton
• The Tie Website: https://thetie.io

Support & Contact

• API Support: api@thetie.io
• GitHub Issues: https://github.com/oregpt/Agenticledger_MCP_TheTieCanton/issues
• MCP Documentation: https://modelcontextprotocol.io

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Version: 1.0.0 Last Updated: 2025-01-17 Platform: AgenticLedger AI Agent Platform