Bankless Onchain MCP Server

Instructions

Implementation Reference

• src/operations/contracts.ts:217-263 (handler)

  The core handler function that fetches the proxy implementation for a given contract address on a specified network using the Bankless API endpoint /find-proxy.

  export async function getProxy(
      network: string,
      contract: string
  ): Promise<Proxy> {
      const token = process.env.BANKLESS_API_TOKEN;
  
      if (!token) {
          throw new BanklessAuthenticationError('BANKLESS_API_TOKEN environment variable is not set');
      }
  
      const endpoint = `${BASE_URL}/chains/${network}/contract/${contract}/find-proxy`;
  
      try {
          const response = await axios.get(
              endpoint,
              {
                  headers: {
                      'Content-Type': 'application/json',
                      'X-BANKLESS-TOKEN': `${token}`
                  }
              }
          );
  
          return response.data;
      } catch (error) {
          if (axios.isAxiosError(error)) {
              const statusCode = error.response?.status || 'unknown';
              const errorMessage = error.response?.data?.message || error.message;
  
              if (statusCode === 401 || statusCode === 403) {
                  throw new BanklessAuthenticationError(`Authentication Failed: ${errorMessage}`);
              } else if (statusCode === 404) {
                  throw new BanklessResourceNotFoundError(`Not Found: ${errorMessage}`);
              } else if (statusCode === 422) {
                  throw new BanklessValidationError(`Validation Error: ${errorMessage}`, error.response?.data);
              } else if (statusCode === 429) {
                  // Extract reset timestamp or default to 60 seconds from now
                  const resetAt = new Date();
                  resetAt.setSeconds(resetAt.getSeconds() + 60);
                  throw new BanklessRateLimitError(`Rate Limit Exceeded: ${errorMessage}`, resetAt);
              }
  
              throw new Error(`Bankless API Error (${statusCode}): ${errorMessage}`);
          }
          throw new Error(`Failed to get proxy information: ${error instanceof Error ? error.message : String(error)}`);
      }
  }

• src/operations/contracts.ts:69-72 (schema)

  Zod schema defining the input parameters for the get_proxy tool: network and contract address.

  export const GetProxySchema = z.object({
      network: z.string().describe('The blockchain network (e.g., "ethereum", "base")'),
      contract: z.string().describe('The contract address to request the proxy implementation contract for'),
  });

• src/index.ts:83-86 (registration)

  Tool registration in the MCP server's listTools handler, specifying name, description, and input schema.

      name: "get_proxy",
      description: "Gets the proxy address for a given network and contract",
      inputSchema: zodToJsonSchema(contracts.GetProxySchema),
  },

• src/index.ts:160-169 (registration)

  Dispatch logic in the MCP server's CallToolRequest handler that validates input with GetProxySchema and invokes the getProxy function.

  case "get_proxy": {
      const args = contracts.GetProxySchema.parse(request.params.arguments);
      const result = await contracts.getProxy(
          args.network,
          args.contract
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }

• src/operations/contracts.ts:93-95 (schema)

  TypeScript type definition for the output of the getProxy function.

  export type Proxy = {
      implementation: string;
  };