Relay MCP Server

Instructions

Implementation Reference

• src/tools/get-supported-tokens.ts:5-67 (handler)

  Main implementation of the get_supported_tokens tool. Contains the tool registration with input schema (Zod) and the handler function that fetches currencies from the Relay API, transforms the response, and returns formatted results with a text summary and JSON data.

  export function register(server: McpServer) {
    server.tool(
      "get_supported_tokens",
      "Search for tokens supported by Relay across chains. Use this to find token contract addresses before getting quotes. Returns token symbol, name, address, and chain availability.",
      {
        chainIds: z
          .array(z.number())
          .optional()
          .describe(
            "Filter to specific chain IDs (e.g. [1, 8453] for Ethereum and Base). Omit for all chains."
          ),
        term: z
          .string()
          .optional()
          .describe(
            'Search by token name or symbol (e.g. "USDC", "ethereum").'
          ),
        verified: z
          .boolean()
          .optional()
          .default(true)
          .describe("Only return verified tokens. Defaults to true."),
        limit: z
          .number()
          .optional()
          .default(20)
          .describe("Max number of token groups to return. Defaults to 20."),
      },
      async ({ chainIds, term, verified, limit }) => {
        const result = await getCurrencies({
          chainIds,
          term,
          verified,
          limit,
        });
  
        const tokens = result.map((group) => {
          const first = group[0];
          return {
            symbol: first.symbol,
            name: first.name,
            chains: group.map((entry) => ({
              chainId: entry.chainId,
              address: entry.address,
              decimals: entry.decimals,
            })),
          };
        });
  
        const summary = `Found ${tokens.length} token${tokens.length !== 1 ? "s" : ""}${term ? ` matching "${term}"` : ""}. ${tokens
          .slice(0, 5)
          .map((t) => `${t.symbol} (on ${t.chains.length} chain${t.chains.length !== 1 ? "s" : ""})`)
          .join(", ")}${tokens.length > 5 ? "..." : ""}.`;
  
        return {
          content: [
            { type: "text", text: summary },
            { type: "text", text: JSON.stringify(tokens, null, 2) },
          ],
        };
      }
    );
  }

• src/tools/get-supported-tokens.ts:10-32 (schema)

  Input validation schema for get_supported_tokens tool. Defines optional parameters: chainIds (array of numbers), term (string for searching token name/symbol), verified (boolean, defaults to true), and limit (number, defaults to 20).

    chainIds: z
      .array(z.number())
      .optional()
      .describe(
        "Filter to specific chain IDs (e.g. [1, 8453] for Ethereum and Base). Omit for all chains."
      ),
    term: z
      .string()
      .optional()
      .describe(
        'Search by token name or symbol (e.g. "USDC", "ethereum").'
      ),
    verified: z
      .boolean()
      .optional()
      .default(true)
      .describe("Only return verified tokens. Defaults to true."),
    limit: z
      .number()
      .optional()
      .default(20)
      .describe("Max number of token groups to return. Defaults to 20."),
  },

• src/index.ts:5-5 (registration)

  Import statement for the get_supported_tokens tool registration function from ./tools/get-supported-tokens.js

  import { register as registerGetSupportedTokens } from "./tools/get-supported-tokens.js";

• src/index.ts:21-21 (registration)

  Registration call that registers the get_supported_tokens tool with the MCP server instance

  registerGetSupportedTokens(server);

• src/relay-api.ts:103-110 (helper)

  Helper function getCurrencies that makes a POST request to the Relay API's /currencies/v1 endpoint with parameters (chainIds, term, verified, limit) and returns a 2D array of CurrencyEntry objects grouped by token

  export async function getCurrencies(
    params: CurrenciesRequest
  ): Promise<CurrencyEntry[][]> {
    return relayApi<CurrencyEntry[][]>("/currencies/v1", {
      method: "POST",
      body: params,
    });
  }