Rhumb

Instructions

Implementation Reference

• packages/mcp/src/tools/execute.ts:17-34 (handler)

  The handler function `handleExecuteCapability` which maps the MCP input to the API client `executeCapability` method.

  export async function handleExecuteCapability(
    input: ExecuteCapabilityInput,
    client: RhumbApiClient
  ): Promise<ExecuteCapabilityOutput> {
    const result = await client.executeCapability(input.capability_id, {
      provider: input.provider,
      method: input.method,
      path: input.path,
      body: input.body,
      params: input.params,
      credentialMode: input.credential_mode,
      idempotencyKey: input.idempotency_key,
      agentToken: input.agent_token,
      xPayment: input.x_payment
    });
  
    return result;
  }

• packages/mcp/src/types.ts:189-204 (schema)

  The input schema definition for the `execute_capability` tool.

  export const ExecuteCapabilityInputSchema = {
    type: "object" as const,
    properties: {
      capability_id: { type: "string" as const, description: "Capability to call (e.g. 'email.send', 'payment.charge'). Get IDs from discover_capabilities or resolve_capability." },
      provider: { type: "string" as const, description: "Specific provider slug (e.g. 'resend', 'stripe'). Omit to let Rhumb auto-select the best healthy provider based on your routing strategy." },
      method: { type: "string" as const, description: "HTTP method (GET, POST, PUT, PATCH, DELETE). Required for byo (BYOK) and agent_vault modes. Not needed for rhumb_managed." },
      path: { type: "string" as const, description: "Provider API path (e.g. '/v3/mail/send'). Get the pattern from resolve_capability. Required for byo (BYOK)/agent_vault. Not needed for rhumb_managed." },
      body: { type: "object" as const, description: "Request body in the provider's native format. See provider docs or resolve_capability for expected structure." },
      params: { type: "object" as const, description: "URL query parameters as key-value pairs" },
      credential_mode: { type: "string" as const, description: "'auto' (default: use Rhumb Resolve when an active managed config exists, otherwise fall back to byo), 'rhumb_managed' (Rhumb Resolve zero-config call path), 'byo' (BYOK via agent_token — requires method+path), or 'agent_vault' (key from credential_ceremony — requires method+path)." },
      idempotency_key: { type: "string" as const, description: "UUID for safe retry — if this request was already processed, returns the cached result instead of re-calling the provider. Required to enable automatic fallback to backup providers on failure." },
      agent_token: { type: "string" as const, description: "Your API token for byo/agent_vault mode. For agent_vault: obtain via credential_ceremony first. Never stored by Rhumb — used for this single call only." },
      x_payment: { type: "string" as const, description: "x402 payment proof (base64 or JSON). Use this to pay per-call with USDC instead of an API key. Pass the proof from a payment_required (402) response. No account or signup needed." }
    },
    required: ["capability_id"] as const
  };

• packages/mcp/src/server.ts:150-174 (registration)

  Registration of the `execute_capability` tool in the MCP server.

  // -- execute_capability ------------------------------------------------
  server.tool(
    "execute_capability",
    "Call a Capability through Rhumb Resolve. Typical workflow: discover_capabilities → resolve_capability → estimate_capability → execute_capability. Default credential mode is auto: Rhumb uses Rhumb Resolve when an active managed config exists, otherwise falls back to byo (BYOK). Other explicit modes: rhumb_managed — zero-config through Rhumb Resolve when available; byo — BYOK via agent_token + method + path; agent_vault — use a key from credential_ceremony via agent_token + method + path. Alternative: pass x_payment for a per-call USDC payment with no account needed. Use check_credentials to see which modes are available.",
    {
      capability_id: z.string().describe(ExecuteCapabilityInputSchema.properties.capability_id.description),
      provider: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.provider.description),
      method: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.method.description),
      path: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.path.description),
      body: z.record(z.string(), z.unknown()).optional().describe(ExecuteCapabilityInputSchema.properties.body.description),
      params: z.record(z.string(), z.string()).optional().describe(ExecuteCapabilityInputSchema.properties.params.description),
      credential_mode: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.credential_mode.description),
      idempotency_key: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.idempotency_key.description),
      agent_token: z.string().optional().describe(ExecuteCapabilityInputSchema.properties.agent_token.description)
    },
    async ({ capability_id, provider, method, path, body, params, credential_mode, idempotency_key, agent_token }) => {
      const result = await handleExecuteCapability(
        { capability_id, provider, method, path, body, params, credential_mode, idempotency_key, agent_token },
        client
      );
      return {
        content: [{ type: "text" as const, text: JSON.stringify(result) }]
      };
    }
  );