Tatum MCP Server

Instructions

Implementation Reference

• src/services/gateway.ts:199-266 (handler)

  The primary handler function implementing the gateway_execute_rpc tool logic. It resolves the gateway URL for the given chain, determines the protocol (REST or JSON-RPC), applies chain-specific formatting, and executes the request.

  public async executeChainRequest({
    chainName,
    method,
    params = []
  }: {
    chainName: string;
    method: string;
    params?: any[];
  }): Promise<TatumApiResponse> {
    try {
      const gatewayUrl = await this.getGatewayUrl(chainName);
      if (!gatewayUrl) {
        return {
          error: `Gateway URL not found for chain: ${chainName}`,
          status: 404,
          statusText: 'Not Found'
        };
      }
  
      const protocol = getChainProtocol(chainName);
      const apiConfig = getChainApiConfig(chainName);
      
      if (protocol === 'rest') {
        // For REST chains, enhance method handling with chain-specific configurations
        let restMethod = method;
        
        // Handle chain-specific method formatting
        if (!method.includes(' ') && !method.startsWith('GET') && !method.startsWith('POST')) {
          // Add base path prefix if configured
          if (apiConfig.basePathPrefix && !method.startsWith(apiConfig.basePathPrefix)) {
            restMethod = `GET ${apiConfig.basePathPrefix}/${method.replace(/^\//, '')}`;
          } else {
            restMethod = `GET /${method.replace(/^\//, '')}`;
          }
        }
        
        // Special handling for specific chains
        if (chainName.startsWith('kadena-')) {
          // Kadena requires specific path structure
          if (!method.includes('chainweb')) {
            const network = chainName.includes('testnet') ? 'testnet04' : 'mainnet01';
            restMethod = `GET /chainweb/0.0/${network}/${method.replace(/^\//, '')}`;
          }
        } else if (chainName.startsWith('cardano-')) {
          // Cardano uses Blockfrost API structure
          if (!method.includes('api/v0')) {
            restMethod = `GET /api/v0/${method.replace(/^\//, '')}`;
          }
        } else if (chainName.startsWith('flow-')) {
          // Flow uses specific v1 API structure
          if (!method.includes('v1')) {
            restMethod = `GET /v1/${method.replace(/^\//, '')}`;
          }
        }
        
        return await this.executeRestRequestWithConfig(gatewayUrl, restMethod, params, apiConfig);
      } else {
        // For JSON-RPC chains like Ethereum
        return await this.executeJsonRpcRequest(gatewayUrl, method, params);
      }
    } catch (error: any) {
      return {
        error: error.message || 'Request failed',
        status: error.status || 500,
        statusText: error.statusText || 'Error'
      };
    }
  }

• src/services/gateway.ts:31-56 (schema)

  Input schema and tool definition for gateway_execute_rpc, used for validation and tool listing.

  {
    name: 'gateway_execute_rpc',
    description: "Execute blockchain RPC calls through Tatum's gateway infrastructure. Supports both JSON-RPC and REST API calls depending on the blockchain. For JSON-RPC methods, use simple method names like 'getblockcount' or 'eth_getBalance'. For REST calls, use full HTTP method and path like 'POST /getnowblock'. Parameters should be provided as an array for JSON-RPC or object for REST calls.",
    inputSchema: {
      type: 'object',
      properties: {
        chain: {
          type: 'string',
          description: "The blockchain network identifier. Examples: 'bitcoin-mainnet', 'ethereum-mainnet', 'litecoin-mainnet', 'polygon-mainnet', 'tron-mainnet', 'bsc-mainnet'. Use gateway_get_supported_chains to see all available networks.",
          examples: ['bitcoin-mainnet', 'ethereum-mainnet', 'litecoin-mainnet', 'polygon-mainnet']
        },
        method: {
          type: 'string',
          description: "The RPC method or REST endpoint to call. For JSON-RPC: use method names like 'getblockcount', 'getbestblockhash', 'eth_getBalance', 'eth_blockNumber'. For REST: use HTTP method + path like 'POST /getnowblock', 'GET /getinfo'. The gateway will automatically detect the protocol based on the format. Use gateway_get_supported_methods to see all available methods.",
          examples: ['getblockcount', 'getbestblockhash', 'eth_getBalance', 'POST /getnowblock']
        },
        params: {
          type: 'array',
          description: "Parameters for the RPC method. For JSON-RPC: provide as array (e.g., ['0x742d35Cc6074C4532895c05b22629ce5b3c28da4', 'latest'] for eth_getBalance). For REST: provide as array with single object element. Leave empty array [] if no parameters needed.",
          items: {},
          default: []
        }
      },
      required: ['chain', 'method']
    }
  }

• src/index.ts:91-100 (registration)

  Tool dispatch registration in the gateway tool switch statement, validating inputs and invoking the handler.

  case 'gateway_execute_rpc':
    if (!args.chain || !args.method) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters: chain, method');
    }
    // Use the new intelligent chain request method
    return await this.gatewayService.executeChainRequest({
      chainName: args.chain,
      method: args.method,
      params: args.params || []
    });

• src/index.ts:193-196 (registration)

  Registration of gateway tools (including schema) in the MCP listTools handler.

  ...GATEWAY_TOOLS.map(tool => ({
    name: tool.name,
    description: `[gateway] ${tool.description}`,
    inputSchema: tool.inputSchema

• src/services/gateway.ts:271-292 (helper)

  Helper function for executing JSON-RPC requests.

  private async executeJsonRpcRequest(url: string, method: string, params: any[] = []): Promise<TatumApiResponse> {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method,
        params
      })
    });
  
    const data = await response.json();
    return {
      data,
      status: response.status,
      statusText: response.statusText
    };
  }