MCP Platform Guide

{
  "mcpServers": {
    "whaletools": {
      "command": "npx",
      "args": ["-y", "whale-code", "mcp", "--store", "your-store-id"],
      "env": {
        "WHALETOOLS_API_KEY": "wt_live_..."
      }
    }
  }
}

{
  "name": "check_warehouse_stock",
  "description": "Check real-time stock levels at a specific warehouse",
  "category": "inventory",
  "input_schema": {
    "type": "object",
    "properties": {
      "sku": {
        "type": "string",
        "description": "Product SKU to check"
      },
      "warehouse_id": {
        "type": "string",
        "description": "Warehouse location identifier"
      }
    },
    "required": ["sku"]
  },
  "handler": {
    "type": "webhook",
    "url": "https://your-api.com/stock/check",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secrets.WAREHOUSE_API_KEY}}"
    }
  },
  "requires_approval": false,
  "visibility": "store"
}

curl -X POST https://gateway.whaletools.dev/v1/stores/{storeId}/custom-tools \
  -H "Authorization: Bearer wt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_shipping_rate",
    "description": "Get shipping rates from carrier API",
    "input_schema": {
      "type": "object",
      "properties": {
        "origin_zip": { "type": "string" },
        "destination_zip": { "type": "string" },
        "weight_oz": { "type": "number" }
      },
      "required": ["origin_zip", "destination_zip", "weight_oz"]
    },
    "handler": {
      "type": "webhook",
      "url": "https://your-api.com/shipping/rates",
      "method": "POST",
      "headers": {
        "X-Carrier-Key": "{{secrets.CARRIER_KEY}}"
      },
      "timeout_ms": 5000
    }
  }'

{
  "name": "calculate_margin",
  "description": "Calculate profit margin for a product",
  "input_schema": {
    "type": "object",
    "properties": {
      "cost": { "type": "number" },
      "price": { "type": "number" }
    },
    "required": ["cost", "price"]
  },
  "handler": {
    "type": "javascript",
    "code": "const margin = ((input.price - input.cost) / input.price) * 100; return { margin: margin.toFixed(2) + '%', profit: (input.price - input.cost).toFixed(2) };"
  }
}

# List recent tool executions
GET /v1/stores/{storeId}/tool-executions
  ?tool=products                    # Filter by tool name
  &agent_id=72d7aaa8-...           # Filter by agent
  &status=success                   # success | error | timeout | pending_approval
  &from=2026-03-01T00:00:00Z       # Start date
  &to=2026-03-10T23:59:59Z         # End date
  &limit=50                         # Results per page
  &offset=0                         # Pagination offset

{
  "executions": [
    {
      "id": "exec_8f3a2b1c",
      "tool": "orders",
      "action": "create_order",
      "agent_id": "72d7aaa8-2e8b-48a0-a38d-f332f69600bb",
      "agent_name": "Sales Assistant",
      "status": "success",
      "duration_ms": 342,
      "input": {
        "customer_id": "cust_abc123",
        "items": [{ "product_id": "prod_xyz", "quantity": 2 }]
      },
      "output": {
        "order_id": "ord_789def",
        "total": 59.98
      },
      "created_at": "2026-03-10T14:23:01Z"
    }
  ],
  "total": 1847,
  "limit": 50,
  "offset": 0
}

// Configure approval at the tool level
PATCH /v1/stores/{storeId}/agents/{agentId}/tool-config
{
  "tool_overrides": {
    "orders": {
      "requires_approval": ["create_order", "cancel_order"],
      "auto_approve": ["list_orders", "get_order"]
    },
    "inventory": {
      "requires_approval": true,
      "approval_conditions": {
        "adjust_stock": {
          "when": "Math.abs(input.quantity) > 100",
          "message": "Large stock adjustment requires approval"
        }
      }
    }
  }
}

# stdio transport — set as environment variable
{
  "env": {
    "WHALETOOLS_API_KEY": "wt_live_sk_a1b2c3d4..."
  }
}

# HTTP/SSE transport — set as Authorization header
Authorization: Bearer wt_live_sk_a1b2c3d4...

# 1. Redirect user to authorization
GET https://whaletools.dev/auth/authorize
  ?client_id=your-app-id
  &redirect_uri=https://your-app.com/callback
  &scope=products:read orders:read orders:write
  &response_type=code

# 2. Exchange authorization code for tokens
POST https://gateway.whaletools.dev/v1/auth/token
{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "client_id": "your-app-id",
  "client_secret": "your-app-secret",
  "redirect_uri": "https://your-app.com/callback"
}

# Response:
{
  "access_token": "eyJhbG...",
  "refresh_token": "rt_...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "products:read orders:read orders:write"
}