yax_get_capabilities

Instructions

Implementation Reference

• sdk-ts/src/index.ts:155-157 (handler)

  SDK method getCapabilities() — calls the remote MCP tool 'yax_get_capabilities' via the low-level call() method, which sends a JSON-RPC tools/call request to the MCP endpoint. This is the primary typed handler in the TypeScript SDK.

  getCapabilities(): Promise<CapabilitiesResponse> {
    return this.call<CapabilitiesResponse>("yax_get_capabilities");
  }

• sdk-ts/src/types.ts:26-39 (schema)

  CapabilitiesResponse interface — defines the typed return shape for yax_get_capabilities, including platform, tagline, proof_points, differentiators, security, tool_categories, getting_started, rate_limits, idempotency, fees, and onboarding fields.

  export interface CapabilitiesResponse {
    ok: boolean;
    platform: string;
    tagline?: string;
    proof_points?: string[];
    differentiators?: Array<{ title: string; detail: string; check_with?: string }>;
    security?: Record<string, unknown>;
    tool_categories?: Array<{ category: string; tools: string[]; when_to_use?: string }>;
    getting_started?: Record<string, string>;
    rate_limits?: Record<string, unknown>;
    idempotency?: { supported_on: string[]; pass_via: string; window: string; replay_response: string };
    fees?: { protocol_fee_bps: number; description: string; rails_routed: string[] };
    onboarding?: Record<string, string>;
  }

• langchain-tools/src/yieldagentx402_langchain/tools.py:33-45 (handler)

  YieldAgentX402DiscoveryTool — LangChain tool that calls 'yax_get_capabilities' via client.call_tool(). This is the LangChain integration handler for the capabilities tool.

  class YieldAgentX402DiscoveryTool(BaseTool):
      name: str = "yieldagentx402_discovery"
      description: str = (
          "Fetch YieldAgentX402 platform capabilities (public, no API key): differentiators, "
          "proof_points, rate_limits, fees, streaming, and onboarding URLs."
      )
      args_schema: Type[BaseModel] = EmptyInput
      mcp_client: Optional[YieldAgentMcpClient] = None
  
      def _run(self) -> str:
          client = self.mcp_client or YieldAgentMcpClient()
          result = client.call_tool("yax_get_capabilities", {})
          return json.dumps(result, indent=2, sort_keys=True)

• langchain-tools/src/yieldagentx402_langchain/tools.py:91-111 (handler)

  YieldAgentX402ActionPlannerTool — LangChain tool that calls 'yax_get_capabilities' and extracts specific fields (platform, tagline, proof_points, getting_started, tool_categories, onboarding) to return a getting-started plan for agents.

  class YieldAgentX402ActionPlannerTool(BaseTool):
      name: str = "yieldagentx402_action_planner"
      description: str = (
          "Return the recommended getting_started sequence and tool categories from "
          "yax_get_capabilities — use before chaining other YieldAgent tools."
      )
      args_schema: Type[BaseModel] = EmptyInput
      mcp_client: Optional[YieldAgentMcpClient] = None
  
      def _run(self) -> str:
          client = self.mcp_client or YieldAgentMcpClient()
          caps = client.call_tool("yax_get_capabilities", {})
          plan = {
              "platform": caps.get("platform"),
              "tagline": caps.get("tagline"),
              "proof_points": caps.get("proof_points"),
              "getting_started": caps.get("getting_started"),
              "tool_categories": caps.get("tool_categories"),
              "onboarding": caps.get("onboarding"),
          }
          return json.dumps(plan, indent=2, sort_keys=True)

• mcp-server/src/yieldagent-client.ts:54-66 (handler)

  callTool() method in YieldAgentMcpClient — contains special-case logic allowing 'yax_get_capabilities' to be called without an API key (introspectionOnly mode). The actual tool call is proxied to the remote MCP server via client.callTool().

  async callTool(params: CallToolRequest["params"]) {
    if (this.config.introspectionOnly && !this.config.apiKey) {
      const name = params?.name ?? "";
      if (name !== "yax_get_capabilities") {
        throw new Error(
          "YAX_API_KEY is required for tools/call (except yax_get_capabilities). Get a key at https://yieldagentx402.app/apply."
        );
      }
    }
  
    const client = await this.connectedClient();
    return client.callTool(params);
  }

• sdk-ts/src/index.ts:86-141 (handler)

  Low-level call() method — the underlying JSON-RPC mechanism used by getCapabilities() to send a 'tools/call' request with the tool name and arguments to the MCP endpoint.

  async call<T = GenericToolResponse>(
    toolName: string,
    args: Record<string, unknown> = {},
    extraHeaders: Record<string, string> = {},
  ): Promise<T> {
    const body: JsonRpcEnvelope = {
      jsonrpc: "2.0",
      id: ++this._id,
      method: "tools/call",
      params: { name: toolName, arguments: args },
    };
  
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      ...extraHeaders,
    };
    if (this.apiKey)  headers["Authorization"] = `Bearer ${this.apiKey}`;
    if (this.agentId) headers["X-Agent-ID"] = this.agentId;
  
    let attempt = 0;
    while (true) {
      const res = await fetch(this.endpoint, {
        ...this._fetchInit,
        method: "POST",
        headers,
        body: JSON.stringify(body),
      });
  
      if (res.status === 429 && attempt < this.maxRetries) {
        const retryAfter = Number(res.headers.get("Retry-After") || "1");
        await new Promise(r => setTimeout(r, Math.max(retryAfter, 1) * 1000));
        attempt++;
        continue;
      }
  
      const json = await res.json();
      if (json.error) {
        throw new YAXError(json.error.message || "JSON-RPC error", "RPC_ERROR", {
          rpcCode: json.error.code,
          raw: json.error,
        });
      }
  
      const result = json.result;
      // MCP 2025-06-18: prefer structuredContent. Fall back to parsing content[0].text.
      const payload = (result?.structuredContent ?? this._parseTextContent(result)) as T & { ok?: boolean; error?: { code?: string; message?: string; hint?: string } };
  
      if (payload && payload.ok === false && payload.error) {
        throw new YAXError(payload.error.message || "Tool error", payload.error.code || "TOOL_ERROR", {
          hint: payload.error.hint,
          raw: payload,
        });
      }
      return payload;
    }
  }