asterpay-mcp-server

Instructions

Implementation Reference

• mcp-server/src/index.ts:317-317 (handler)

  The handler function for check_token_tiers tool - calls the AsterPay API endpoint /v1/token/tiers and formats the response

  async () => formatResponse(await callApi("GET", "/v1/token/tiers"))

• mcp-server/src/index.ts:313-318 (registration)

  Registration of check_token_tiers tool with MCP server - defines tool name, description, empty schema (no parameters), and handler

  server.tool(
    "check_token_tiers",
    "View ASTERPAY token tier system — hold ASTERPAY tokens for API discounts up to 60% off. FREE.",
    {},
    async () => formatResponse(await callApi("GET", "/v1/token/tiers"))
  );

• mcp-server/src/index.ts:316-316 (schema)

  Empty schema object indicating the tool takes no input parameters

  {},

• mcp-server/src/index.ts:25-50 (helper)

  Helper function that makes HTTP requests to the AsterPay API - handles GET/POST methods and 402 payment required responses

  async function callApi(
    method: "GET" | "POST",
    path: string,
    body?: Record<string, unknown>
  ): Promise<{ status: number; data: unknown; paymentRequired?: unknown }> {
    const url = `${API_BASE}${path}`;
    const headers: Record<string, string> = { "Content-Type": "application/json" };
  
    const res = await fetch(url, {
      method,
      headers,
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
  
    const data = await res.json();
  
    if (res.status === 402) {
      return {
        status: 402,
        data: null,
        paymentRequired: data,
      };
    }
  
    return { status: res.status, data };
  }

• mcp-server/src/index.ts:55-104 (helper)

  Helper function that formats API responses for MCP tool output - handles both successful responses and payment-required (402) responses with formatted payment instructions

  function formatResponse(result: { status: number; data: unknown; paymentRequired?: unknown }): {
    content: Array<{ type: "text"; text: string }>;
  } {
    if (result.status === 402) {
      const pr = result.paymentRequired as Record<string, unknown>;
      const accepts = (pr?.accepts as Array<Record<string, unknown>>)?.[0];
      const amount = accepts?.amount
        ? `${(parseInt(accepts.amount as string) / 1e6).toFixed(6)} USDC`
        : "unknown";
      const network = (accepts?.network as string) || "unknown";
  
      return {
        content: [
          {
            type: "text",
            text: [
              "Payment required to access this endpoint.",
              "",
              `Amount: ${amount}`,
              `Network: ${network}`,
              `Asset: USDC`,
              `Pay to: ${(accepts?.payTo as string) || "unknown"}`,
              "",
              "To use this endpoint, send an x402 payment via @x402/fetch or the AsterPay SDK.",
              "Install: npm install @x402/fetch",
              "",
              "Example:",
              "```",
              'import { wrapFetch } from "@x402/fetch";',
              'const fetchWithPay = wrapFetch(fetch, wallet);',
              `const res = await fetchWithPay("${API_BASE}${(pr?.resource as Record<string, unknown>)?.url || ""}");`,
              "```",
              "",
              "Docs: https://x402-api-production-ba87.up.railway.app/docs",
              "Discovery: https://x402-api-production-ba87.up.railway.app/discovery/resources",
            ].join("\n"),
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.data, null, 2),
        },
      ],
    };
  }