EVM MCP Server

Instructions

Implementation Reference

• src/core/tools.ts:521-551 (registration)

  Full registration of the 'get_transaction_receipt' MCP tool, including input schema, annotations, and inline handler function that uses viem's public client to fetch the transaction receipt.

  server.registerTool(
    "get_transaction_receipt",
    {
      description: "Get transaction receipt (confirmation status, gas used, logs). Use this to check if a transaction has been confirmed.",
      inputSchema: {
        txHash: z.string().describe("Transaction hash (0x...)"),
        network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.")
      },
      annotations: {
        title: "Get Transaction Receipt",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true
      }
    },
    async ({ txHash, network = "ethereum" }) => {
      try {
        const client = await services.getPublicClient(network);
        const receipt = await client.getTransactionReceipt({
          hash: txHash as Hash
        });
        return { content: [{ type: "text", text: services.helpers.formatJson(receipt) }] };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error fetching transaction receipt: ${error instanceof Error ? error.message : String(error)}` }],
          isError: true
        };
      }
    }
  );

• src/core/tools.ts:537-550 (handler)

  The inline handler function that implements the core logic: fetches public client, calls getTransactionReceipt with the hash, formats the receipt as JSON, and returns it in the MCP response format. Handles errors gracefully.

  async ({ txHash, network = "ethereum" }) => {
    try {
      const client = await services.getPublicClient(network);
      const receipt = await client.getTransactionReceipt({
        hash: txHash as Hash
      });
      return { content: [{ type: "text", text: services.helpers.formatJson(receipt) }] };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error fetching transaction receipt: ${error instanceof Error ? error.message : String(error)}` }],
        isError: true
      };
    }
  }

• src/core/tools.ts:523-536 (schema)

  Tool metadata including description, Zod input schema validating txHash (required string) and network (optional string), and annotations indicating read-only, idempotent behavior.

  {
    description: "Get transaction receipt (confirmation status, gas used, logs). Use this to check if a transaction has been confirmed.",
    inputSchema: {
      txHash: z.string().describe("Transaction hash (0x...)"),
      network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.")
    },
    annotations: {
      title: "Get Transaction Receipt",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },

• src/core/services/transactions.ts:18-23 (helper)

  Helper utility function to get transaction receipt, wrapping viem client call. Not directly used by the tool handler but provides the same functionality.

   * Get a transaction receipt by hash for a specific network
   */
  export async function getTransactionReceipt(hash: Hash, network = 'ethereum'): Promise<TransactionReceipt> {
    const client = getPublicClient(network);
    return await client.getTransactionReceipt({ hash });
  }