X402 MCP Template

Instructions

Implementation Reference

• index.ts:309-353 (handler)

  The handler logic for the 'health_check' tool. It attempts to GET the /health endpoint using axios (non-payment client) with a 5-second timeout. Returns a JSON-formatted response indicating 'healthy' status with API details if successful, or 'error' status with error message if failed.

  case "health_check": {
    try {
      // Try health endpoint
      const response = await axios.get(`${baseURL}/health`, { timeout: 5000 });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                status: "healthy",
                api_url: baseURL,
                payment_enabled: paymentEnabled,
                network: network,
                response: response.data,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                status: "error",
                api_url: baseURL,
                payment_enabled: paymentEnabled,
                network: network,
                error: error.message,
                note: "API may be down or health endpoint not available",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  }

• index.ts:138-145 (schema)

  The tool definition including name, description, and empty input schema (no parameters required) as returned by the listTools handler.

  {
    name: "health_check",
    description: "Check if the X402 API service is available and responding",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• index.ts:106-148 (registration)

  The listTools request handler where the 'health_check' tool is registered in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "example_api_call",
          description: "Example tool for making X402-protected API calls. Replace with your actual API endpoints.",
          inputSchema: {
            type: "object",
            properties: {
              query: {
                type: "string",
                description: "Example query parameter - customize for your API",
              },
              limit: {
                type: "number",
                description: "Optional: Maximum number of results to return",
                minimum: 1,
                maximum: 100,
                default: 10,
              },
            },
            required: ["query"],
          },
        },
        {
          name: "service_info",
          description: "Get information about the X402 API service including available endpoints, pricing, and payment requirements",
          inputSchema: {
            type: "object",
            properties: {},
          },
        },
        {
          name: "health_check",
          description: "Check if the X402 API service is available and responding",
          inputSchema: {
            type: "object",
            properties: {},
          },
        },
      ],
    };
  });