Alchemy MCP Server

Implementation Reference

• index.ts:145-169 (registration)

  Registers the MCP tool 'fetchTokensOwnedByMultichainAddresses' with Zod input schema and an async handler that calls alchemyApi.getTokensByMultichainAddress and formats the response.
  server.tool('fetchTokensOwnedByMultichainAddresses', { addresses: z.array(z.object({ address: z.string().describe('The wallet address to query. e.g. "0x1234567890123456789012345678901234567890"'), networks: z.array(z.string()).describe('The blockchain networks to query. e.g. ["eth-mainnet", "base-mainnet"]') })).describe('A list of wallet address and network pairs'), }, async (params) => { try { const result = await alchemyApi.getTokensByMultichainAddress(params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; } catch (error) { if (error instanceof Error) { console.error('Error in getTokensByMultichainAddress:', error); return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true }; } return { content: [{ type: "text", text: 'Unknown error occurred' }], isError: true }; } });
• api/alchemyApi.ts:65-82 (handler)

  Core implementation of the tool logic: creates Alchemy multi-chain token client, posts request to /by-address endpoint, processes response by converting hex balances to decimals using helper.
  async getTokensByMultichainAddress(params: MultiChainTokenByAddress) { try { const client = createMultiChainTokenClient(); const response = await client.post('/by-address', { addresses: params.addresses.map((pair: AddressPair) => ({ address: pair.address, networks: pair.networks })) }); const responseData = convertHexBalanceToDecimal(response); return responseData; } catch (error) { console.error('Error fetching token data:', error); throw error; } },
• index.ts:146-149 (schema)

  Zod schema defining the input parameters for the tool: array of address-network pairs.
  addresses: z.array(z.object({ address: z.string().describe('The wallet address to query. e.g. "0x1234567890123456789012345678901234567890"'), networks: z.array(z.string()).describe('The blockchain networks to query. e.g. ["eth-mainnet", "base-mainnet"]') })).describe('A list of wallet address and network pairs'),
• types/types.d.ts:23-25 (schema)

  TypeScript interface defining the input type MultiChainTokenByAddress used in alchemyApi.
  export interface MultiChainTokenByAddress { addresses: AddressPair[]; }
• utils/convertHexBalanceToDecimal.ts:1-35 (helper)

  Helper utility that converts hexadecimal token balances from Alchemy API response to readable decimal values, handling token decimals.
  export default function convertHexBalanceToDecimal(response: any) { // Handle nested data structure - API returns { data: { data: { tokens: [...] } } } const responseData = response.data && response.data.data ? response.data.data : response.data; // Process tokens if they exist // LLMs are very bad at arithmetic, so we need to convert the hex balances to decimal if (responseData.tokens && Array.isArray(responseData.tokens)) { // Convert hex balances to decimal responseData.tokens = responseData.tokens.map((token: any) => { try { const processedToken = { ...token }; const hexTokenBalance = token.tokenBalance; const tokenDecimals = parseInt(token.tokenMetadata.decimals || '18', 10); const bigIntBalance = BigInt(hexTokenBalance); const decimalBalance = Number(bigIntBalance) / Math.pow(10, tokenDecimals); // Store both formats processedToken.originalHexBalance = hexTokenBalance; processedToken.tokenBalance = decimalBalance; return processedToken; } catch (error) { // On error, return token with balance as 0 but keep original hex return { ...token, originalHexBalance: token.tokenBalance, tokenBalance: 0 }; } }); } return responseData; }
• api/alchemyClients.ts:18-25 (helper)

  Helper function that creates configured axios client for Alchemy's multi-chain tokens API endpoint.
  export const createMultiChainTokenClient = () => axios.create({ baseURL: `https://api.g.alchemy.com/data/v1/${API_KEY}/assets/tokens`, headers: { 'accept': 'application/json', 'content-type': 'application/json', 'x-alchemy-client-breadcrumb': BREADCRUMB_HEADER }, });