Relay MCP Server

Instructions

Implementation Reference

• src/tools/get-transaction-status.ts:5-59 (handler)

  The main handler implementation that registers the 'get_transaction_status' MCP tool, including its schema definition (requestId parameter) and the async handler function that calls getIntentStatus, formats status messages based on the response, and returns both a human-readable summary and the raw status data.

  export function register(server: McpServer) {
    server.tool(
      "get_transaction_status",
      `Check the status of a Relay bridge or swap transaction. Use the requestId returned from execute_bridge.
  
  Statuses:
    waiting  — The origin chain transaction has been broadcast but not yet confirmed on-chain. Just wait — no further action needed.
    pending  — The relay network has picked up the request and is processing the cross-chain transfer.
    success  — Complete. Funds have arrived on the destination chain.
    failure  — The transaction failed.
    refund   — The transaction was refunded to the sender.
  
  IMPORTANT: After the wallet "execute" action completes all steps (approval + deposit), Relay handles the cross-chain delivery automatically. Poll every 5-10 seconds until success or failure. The user does NOT need to do anything else after execution completes — just wait.`,
      {
        requestId: z
          .string()
          .describe(
            "The request ID returned from execute_bridge or from a quote's steps[].requestId."
          ),
      },
      async ({ requestId }) => {
        const status = await getIntentStatus(requestId);
  
        const trackingUrl = `https://relay.link/transaction/${requestId}`;
  
        let summary: string;
        switch (status.status) {
          case "success":
            summary = `Transaction complete! Destination tx: ${status.txHashes?.join(", ") || "pending confirmation"}.\n\nView on Relay: ${trackingUrl}`;
            break;
          case "pending":
            summary = "Transaction is being processed by the relay network.";
            break;
          case "waiting":
            summary = "Transaction submitted, waiting to be picked up by the relay network.";
            break;
          case "failure":
            summary = "Transaction failed. Check the requestId and try again.";
            break;
          case "refund":
            summary = "Transaction was refunded to the sender.";
            break;
          default:
            summary = `Transaction status: ${status.status}.`;
        }
  
        return {
          content: [
            { type: "text", text: summary },
            { type: "text", text: JSON.stringify(status, null, 2) },
          ],
        };
      }
    );
  }

• src/index.ts:10-26 (registration)

  Tool registration: imports the register function from get-transaction-status.ts and calls it with the MCP server instance to enable the tool.

  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);
  registerExecuteBridge(server);
  registerGetTransactionStatus(server);

• src/relay-api.ts:222-237 (helper)

  Helper function that defines the IntentStatus interface and provides getIntentStatus which makes an API call to the Relay API's /intents/status/v3 endpoint to retrieve transaction status for a given requestId.

  export interface IntentStatus {
    status: string;
    inTxHashes?: string[];
    txHashes?: string[];
    originChainId?: number;
    destinationChainId?: number;
    updatedAt?: string;
  }
  
  export async function getIntentStatus(
    requestId: string
  ): Promise<IntentStatus> {
    return relayApi<IntentStatus>("/intents/status/v3", {
      params: { requestId },
    });
  }

• src/tools/get-transaction-status.ts:18-24 (schema)

  Input schema definition using Zod: defines the requestId parameter as a required string with a description of its source.

  {
    requestId: z
      .string()
      .describe(
        "The request ID returned from execute_bridge or from a quote's steps[].requestId."
      ),
  },

• src/relay-api.ts:222-229 (schema)

  Output schema definition: TypeScript interface defining the structure of the IntentStatus response from the Relay API, including status, transaction hashes, chain IDs, and timestamp.

  export interface IntentStatus {
    status: string;
    inTxHashes?: string[];
    txHashes?: string[];
    originChainId?: number;
    destinationChainId?: number;
    updatedAt?: string;
  }