x402 MCP Server

Instructions

Implementation Reference

• src/index.ts:645-692 (handler)

  The x402_web_search tool handler is defined in src/index.ts. It handles both paid searches (via Tavily if PRIVATE_KEY is set) and a free test mode.

  server.tool(
    "x402_web_search",
    `Search the web and return ranked results via Tavily — title, URL, snippet, and relevance score.
  Price: $0.01 USDC per search (paid mode) | Free test: returns fixture data.
  
  Optional synthesized answer summarizing results. Use include_domains/exclude_domains for focused research.
  Per-wallet daily limit: 50 queries (resets midnight UTC).
  Without X402_PRIVATE_KEY, only the free test endpoint is available.
  
  Returns: query, results array (title, url, snippet, score), optional answer field.`,
    {
      query: z.string().min(1).max(400).describe("Search query (max 400 chars)"),
      max_results: z.number().int().min(1).max(10).default(5)
        .describe("Number of results to return (1-10, default: 5)"),
      include_answer: z.boolean().default(false)
        .describe("Include a synthesized answer above the results (may be null if Tavily cannot synthesize)"),
      include_domains: z.array(z.string()).max(20).optional()
        .describe("Restrict results to these domains only (max 20)"),
      exclude_domains: z.array(z.string()).max(20).optional()
        .describe("Exclude these domains from results (max 20)"),
    },
    async (params) => {
      const base = APIS.search.baseUrl;
      try {
        const usePaid = !!PRIVATE_KEY;
        if (usePaid) {
          const payload: Record<string, unknown> = {
            query: params.query,
            max_results: params.max_results,
            include_answer: params.include_answer,
          };
          if (params.include_domains) payload.include_domains = params.include_domains;
          if (params.exclude_domains) payload.exclude_domains = params.exclude_domains;
          const data = await apiPost(base, "/search", payload, true);
          return textResult({ mode: "paid", cost: "$0.01", ...data });
        } else {
          const data = await apiGet(base, "/search/test");
          return textResult({
            mode: "free_test",
            note: "Free test — returns fixture data. Set X402_PRIVATE_KEY for live web search.",
            ...data,
          });
        }
      } catch (err: any) {
        return errorResult(err.message);
      }
    }
  );