Relay MCP Server

Instructions

Implementation Reference

• src/tools/estimate-fees.ts:23-78 (handler)

  Main handler function that executes the estimate_fees tool. It calls getQuote API, extracts fee details, and returns a formatted response with gas fees, relayer fees, and total cost impact.

  async ({
    originChainId,
    destinationChainId,
    originCurrency,
    destinationCurrency,
    amount,
    sender,
  }) => {
    const quote = await getQuote({
      user: sender,
      originChainId,
      destinationChainId,
      originCurrency,
      destinationCurrency,
      amount,
    });
  
    const { fees, details } = quote;
  
    const summary = `Fee estimate for ${details.currencyIn.amountFormatted} ${details.currencyIn.currency.symbol} → ${details.currencyOut.currency.symbol}: Gas $${fees.gas.amountUsd}, Relayer $${fees.relayer.amountUsd}. Total impact: ${details.totalImpact.percent}% ($${details.totalImpact.usd}).`;
  
    return {
      content: [
        { type: "text", text: summary },
        {
          type: "text",
          text: JSON.stringify(
            {
              gas: {
                amount: fees.gas.amountFormatted,
                symbol: fees.gas.currency.symbol,
                usd: fees.gas.amountUsd,
              },
              relayer: {
                amount: fees.relayer.amountFormatted,
                symbol: fees.relayer.currency.symbol,
                usd: fees.relayer.amountUsd,
              },
              relayerGas: {
                amount: fees.relayerGas.amountFormatted,
                usd: fees.relayerGas.amountUsd,
              },
              relayerService: {
                amount: fees.relayerService.amountFormatted,
                usd: fees.relayerService.amountUsd,
              },
              totalImpact: details.totalImpact,
              timeEstimateSeconds: details.timeEstimate,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/estimate-fees.ts:9-22 (schema)

  Zod input schema definition for the estimate_fees tool. Validates originChainId, destinationChainId, originCurrency, destinationCurrency, amount, and sender parameters.

  {
    originChainId: z.number().describe("Source chain ID."),
    destinationChainId: z.number().describe("Destination chain ID."),
    originCurrency: z
      .string()
      .describe('Origin token address. "0x0000000000000000000000000000000000000000" for native.'),
    destinationCurrency: z
      .string()
      .describe('Destination token address. "0x0000000000000000000000000000000000000000" for native.'),
    amount: z
      .string()
      .describe("Amount in the origin token's smallest unit."),
    sender: z.string().describe("Sender wallet address."),
  },

• src/tools/estimate-fees.ts:5-79 (registration)

  Tool registration function that registers 'estimate_fees' with the MCP server, including the tool name, description, schema, and handler.

  export function register(server: McpServer) {
    server.tool(
      "estimate_fees",
      "Estimate the fees for a bridge or swap without committing to execution. Returns a breakdown of gas fees, relayer fees, and total cost impact. Useful for comparing routes or showing users expected costs.",
      {
        originChainId: z.number().describe("Source chain ID."),
        destinationChainId: z.number().describe("Destination chain ID."),
        originCurrency: z
          .string()
          .describe('Origin token address. "0x0000000000000000000000000000000000000000" for native.'),
        destinationCurrency: z
          .string()
          .describe('Destination token address. "0x0000000000000000000000000000000000000000" for native.'),
        amount: z
          .string()
          .describe("Amount in the origin token's smallest unit."),
        sender: z.string().describe("Sender wallet address."),
      },
      async ({
        originChainId,
        destinationChainId,
        originCurrency,
        destinationCurrency,
        amount,
        sender,
      }) => {
        const quote = await getQuote({
          user: sender,
          originChainId,
          destinationChainId,
          originCurrency,
          destinationCurrency,
          amount,
        });
  
        const { fees, details } = quote;
  
        const summary = `Fee estimate for ${details.currencyIn.amountFormatted} ${details.currencyIn.currency.symbol} → ${details.currencyOut.currency.symbol}: Gas $${fees.gas.amountUsd}, Relayer $${fees.relayer.amountUsd}. Total impact: ${details.totalImpact.percent}% ($${details.totalImpact.usd}).`;
  
        return {
          content: [
            { type: "text", text: summary },
            {
              type: "text",
              text: JSON.stringify(
                {
                  gas: {
                    amount: fees.gas.amountFormatted,
                    symbol: fees.gas.currency.symbol,
                    usd: fees.gas.amountUsd,
                  },
                  relayer: {
                    amount: fees.relayer.amountFormatted,
                    symbol: fees.relayer.currency.symbol,
                    usd: fees.relayer.amountUsd,
                  },
                  relayerGas: {
                    amount: fees.relayerGas.amountFormatted,
                    usd: fees.relayerGas.amountUsd,
                  },
                  relayerService: {
                    amount: fees.relayerService.amountFormatted,
                    usd: fees.relayerService.amountUsd,
                  },
                  totalImpact: details.totalImpact,
                  timeEstimateSeconds: details.timeEstimate,
                },
                null,
                2
              ),
            },
          ],
        };
      }
    );

• src/index.ts:8-24 (registration)

  Imports the estimate_fees registration and calls it with the MCP server instance to activate the tool.

  import { register as registerEstimateFees } from "./tools/estimate-fees.js";
  import { register as registerExecuteBridge } from "./tools/execute-bridge.js";
  import { register as registerGetTransactionStatus } from "./tools/get-transaction-status.js";
  import { register as registerGetTransactionHistory } from "./tools/get-transaction-history.js";
  import { register as registerGetRelayAppUrl } from "./tools/get-relay-app-url.js";
  import { register as registerWallet } from "./tools/wallet.js";
  
  const server = new McpServer({
    name: "relay-mcp",
    version: "0.1.0",
  });
  
  registerGetSupportedChains(server);
  registerGetSupportedTokens(server);
  registerGetBridgeQuote(server);
  registerGetSwapQuote(server);
  registerEstimateFees(server);

• src/relay-api.ts:212-220 (helper)

  Helper function getQuote that makes the actual API call to the Relay API's /quote/v2 endpoint to fetch fee estimates and transaction details.

  export async function getQuote(params: QuoteRequest): Promise<QuoteResponse> {
    return relayApi<QuoteResponse>("/quote/v2", {
      method: "POST",
      body: {
        ...params,
        tradeType: params.tradeType || "EXACT_INPUT",
      },
    });
  }