agentoracle-mcp

Instructions

Implementation Reference

• src/index.ts:34-81 (handler)

  The handler function for the 'research' tool in AgentOracle MCP, which makes a POST request to the research endpoint and handles potential payment requirements.

  async ({ query }) => {
    try {
      const response = await fetch(RESEARCH_ENDPOINT, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ query }),
      });
  
      if (response.status === 402) {
        const paymentInfo = await response.json();
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  status: "payment_required",
                  message: "This query requires a $0.02 USDC payment on Base mainnet via x402 protocol.",
                  instructions: "Use an x402-compatible client to sign a USDC payment and include it in the X-PAYMENT header.",
                  payment_details: paymentInfo,
                  endpoint: RESEARCH_ENDPOINT,
                  manifest: MANIFEST_ENDPOINT,
                },
                null,
                2
              ),
            },
          ],
        };
      }
  
      if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        return {
          content: [{ type: "text", text: `Research request failed (HTTP ${response.status}): ${JSON.stringify(errorData)}` }],
          isError: true,
        };
      }
  
      const data = await response.json();
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error connecting to AgentOracle: ${error instanceof Error ? error.message : String(error)}` }],
        isError: true,
      };
    }
  }

• src/index.ts:23-82 (registration)

  Registration of the 'research' tool with its schema definition and handler.

  server.tool(
    "research",
    "Perform real-time research on any topic using AgentOracle. Returns structured results with summary, key facts, cited sources, and confidence score. Costs $0.02 USDC per query via x402 on Base mainnet.",
    {
      query: z
        .string()
        .max(2000)
        .describe(
          "Natural language research question. Examples: 'What are the latest AI chip architectures?', 'Compare React vs Vue in 2026', 'Latest funding rounds in autonomous agents space'"
        ),
    },
    async ({ query }) => {
      try {
        const response = await fetch(RESEARCH_ENDPOINT, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ query }),
        });
  
        if (response.status === 402) {
          const paymentInfo = await response.json();
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(
                  {
                    status: "payment_required",
                    message: "This query requires a $0.02 USDC payment on Base mainnet via x402 protocol.",
                    instructions: "Use an x402-compatible client to sign a USDC payment and include it in the X-PAYMENT header.",
                    payment_details: paymentInfo,
                    endpoint: RESEARCH_ENDPOINT,
                    manifest: MANIFEST_ENDPOINT,
                  },
                  null,
                  2
                ),
              },
            ],
          };
        }
  
        if (!response.ok) {
          const errorData = await response.json().catch(() => ({}));
          return {
            content: [{ type: "text", text: `Research request failed (HTTP ${response.status}): ${JSON.stringify(errorData)}` }],
            isError: true,
          };
        }
  
        const data = await response.json();
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error connecting to AgentOracle: ${error instanceof Error ? error.message : String(error)}` }],
          isError: true,
        };
      }
    }
  );