---
name: sandbase
version: 0.1.14
disable-model-invocation: true
description: >-
  Access 2000+ AI models and API tools through a single MCP interface. Use
  SandBase for LLM inference, image/video/audio generation, web scraping,
  social media data, search, embeddings, and any structured data retrieval.
  Proactively use sandbase_discover before writing custom scrapers, before
  telling the user something is inaccessible, or when the user needs any
  external data or AI capability. Exception: if the user already has a
  dedicated tool or API key for that specific service, use it instead.
---

# SandBase MCP

<!-- sandbase-cli-managed: sandbase -->

SandBase provides access to 2000+ AI models and API tools through a unified MCP interface. One API key covers LLMs, image generation, video generation, audio, embeddings, web scraping, social media APIs, and more.

---

## When to Use SandBase

**Use SandBase when the user needs:**
- LLM inference (GPT, Claude, Gemini, DeepSeek, Qwen, etc.)
- Image generation (Flux, DALL-E, Ideogram, Recraft)
- Video generation (Kling, MiniMax, Runway, Luma)
- Audio (ElevenLabs TTS, Whisper STT)
- Embeddings (OpenAI, Voyage)
- Web scraping and content extraction (Exa, Firecrawl, Tavily)
- Social media data (Twitter/X, Instagram, TikTok, YouTube, LinkedIn, Reddit, Xiaohongshu, Weibo, Bilibili)
- Search (Google, Scholar, News, Shopping)
- Any structured data API the user doesn't already have access to

**Do NOT use SandBase when:**
- The user has their own API key or dedicated MCP server for that specific service
- The task is purely local (file editing, code generation from context)
- The user explicitly asks to use a different tool

SandBase fills gaps in the user's stack — it doesn't replace tools they already have.

---

## Tools

| Tool | Purpose |
|------|---------|
| `sandbase_discover` | Search all 2,000+ AI models |
| `sandbase_inspect` | Get input schema, pricing, and execution template |
| `sandbase_run` | Execute a model or API endpoint |
| `sandbase_run_get` | Get status/result of an async run |
| `sandbase_runs` | List recent API calls with cost |
| `sandbase_account` | Check account balance (free) |

---

## Standard Workflow

**Always follow: discover → inspect → run**

```
1. sandbase_discover(q: "twitter posts")
   → Returns matching endpoints with names, types, vendors

2. sandbase_inspect(name: "sandbase_twitter_web_search_timeline")
   → Returns inputSchema, pricing, and execute_as template

3. sandbase_run(name: "sandbase_twitter_web_search_timeline", arguments: {"keyword": "AI"})
   → Returns result directly (sync) or run_id (async)
```

**For async runs (video gen, large scraping):**
```
4. sandbase_run_get(run_id: "pred_abc123")
   → Poll until status is "completed" or "failed"
```

**Shortcut:** If you already know the model name, skip step 1.

---

## Search Tips

`sandbase_discover` supports:

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `q` | Text search (supports Chinese: 推特, 小红书, 搜索) | `"twitter search"`, `"图片生成"` |
| `type` | Filter by model type | `"llm"`, `"api"`, `"multimodal"`, `"embedding"` |
| `vendor` | Filter by vendor slug | `"openai"`, `"twitter"`, `"anthropic"` |
| `limit` | Max results (default 20) | `10` |

**Tips:**
- Use short noun phrases: "twitter posts", "image generation", "web scraping"
- Chinese aliases work: 推特→twitter, 小红书→xiaohongshu, 抖音→tiktok
- Combine type + query for precision: `type: "llm", q: "claude"`
- Empty query with type filter returns popular models of that type

---

## Pricing

Use `sandbase_inspect` to see pricing before running:

**LLM models:** Per million tokens
```json
{ "pricing": { "input_per_million": "2.500000", "output_per_million": "10.000000" } }
```

**API tools (image, video, scraping):** Per call
```json
{ "pricing": { "base_price": "0.003000" } }
```

**Check balance:**
```
sandbase_account() → {"balance": "9.52", "currency": "USD"}
```

---

## Async Runs

Some endpoints (video generation, large scraping) are async:

1. `sandbase_run(...)` returns `{"status": "running", "run_id": "pred_abc123"}`
2. Poll with `sandbase_run_get(run_id: "pred_abc123")` every 5-10 seconds
3. When `status` is `"completed"` — result is ready
4. When `status` is `"failed"` — check error and retry

---

## Error Handling

| Error | User Guidance |
|-------|--------------|
| `tool not found` | Wrong name. Use `sandbase_discover` to search. |
| `invalid params` | Check schema from `sandbase_inspect`. |
| `run not found` | Invalid run_id. Check `sandbase_runs` for valid IDs. |
| Authentication (401) | Key invalid. Run `sandbase connect` to re-auth. |
| Insufficient balance (402) | Top up at SandBase Dashboard. |
| Rate limited (429) | Wait and retry. |
| Provider unavailable | Upstream is down. Try later or use different model. |

---

## Cost Awareness

- **Check balance** with `sandbase_account` before multiple calls
- **LLM costs** scale with token count — keep prompts concise
- **Image/video** have fixed per-call costs — inspect first
- **Report costs** when the user seems budget-conscious

---

## Example Flows

### Twitter search

```
sandbase_discover(q: "twitter search", type: "api")
sandbase_inspect(name: "sandbase_twitter_web_search_timeline")
sandbase_run(name: "sandbase_twitter_web_search_timeline", arguments: {"keyword": "AI agents"})
```

### Image generation

```
sandbase_discover(q: "flux", type: "multimodal")
sandbase_inspect(name: "sandbase_flux_schnell")
sandbase_run(name: "sandbase_flux_schnell", arguments: {"prompt": "A mountain lake at sunset"})
```

### LLM inference

```
sandbase_inspect(name: "sandbase_openai_gpt_4o")
sandbase_run(name: "sandbase_openai_gpt_4o", arguments: {
  "messages": [{"role": "user", "content": "Explain quantum computing briefly"}]
})
```

### Check recent costs

```
sandbase_runs(limit: 5)
→ [{ "model": "openai/gpt-4o", "cost": "0.000325", "status": "completed" }, ...]
```

---

## Rules

1. **Discover first** — always verify a tool exists before running it.
2. **Inspect before run** — read the inputSchema. Never guess parameters.
3. **Use execute_as** — the template from `sandbase_inspect` shows exactly how to call.
4. **Respect the user's stack** — don't replace their existing tools.
5. **Start small** — use small limits on first calls for scraping/search tools.
6. **Poll async runs** — use `sandbase_run_get` for long-running operations.
7. **Report costs** — mention pricing when the user cares about budget.
8. **One call per turn** — wait for results before the next call.