CLI, MCP and SDK Access

There are now more ways to query COLA Cloud than ever. You can write Python, write TypeScript, pipe commands in a terminal, or just ask an AI assistant in plain English. They all hit the same API, share the same quotas, and return the same data.

Here's what's available and why it matters.

The Python SDK

Install with pip install colacloud. Works with Python 3.10+, supports both sync and async clients, and has full type hints so your editor can help.

from colacloud import ColaCloud

with ColaCloud(api_key="cola_xxxx") as client:
    results = client.colas.list(
        q="cabernet",
        product_type="wine",
        origin="California",
    )
    for cola in results.data:
        print(f"{cola.brand_name}: {cola.product_name}")

Need to iterate through thousands of results? The SDK handles pagination automatically:

for cola in client.colas.iterate(q="bourbon"):
    print(cola.ttb_id, cola.brand_name)

There's also an async client for high-throughput workloads. Same interface, just await everything.

The JavaScript SDK

Install with npm install colacloud. Zero external dependencies — it uses native fetch, so it works in Node.js 18+ and modern browsers without a bundler.

import { ColaCloud } from 'colacloud';

const client = new ColaCloud({ apiKey: 'cola_xxxx' });

const results = await client.colas.list({
  q: 'bourbon',
  productType: 'distilled spirits',
  perPage: 10,
});

for (const cola of results.data) {
  console.log(`${cola.brand_name} - ${cola.product_name}`);
}

Full TypeScript support included. Async iterators work the same way as the Python SDK.

The CLI

Install with pip install colacloud-cli. Set your API key once and you're querying from the terminal:

$ cola config set-key
$ cola colas search "buffalo trace"
$ cola colas list --product-type wine --origin california --limit 20
$ cola barcode 012345678901

Output is a human-readable table by default. Add --json and pipe to jq for scripting:

$ cola colas list -q "whiskey" --json | jq '.data[].brand_name'

The CLI is especially useful for quick lookups, ad-hoc exploration, and piping COLA data into other tools. It's the closest thing to running a SQL query without actually writing SQL.

The MCP server

This is the newest addition, and arguably the most interesting one. MCP (Model Context Protocol) lets AI assistants like Claude use tools directly. Our MCP server runs on Cloudflare's edge network — there's nothing to install.

Add this to your Claude Desktop or Claude Code config:

{
  "mcpServers": {
    "colacloud": {
      "url": "https://mcp.colacloud.us/mcp",
      "headers": {
        "Authorization": "Bearer cola_xxxx"
      }
    }
  }
}

Then just ask questions in natural language:

• "Find bourbon products from Kentucky approved this year"
• "Look up the product with barcode 012345678901"
• "Show me the biggest wine permittees in California"

The assistant calls the right API endpoints, handles pagination, and presents the results conversationally. Six tools are exposed — search COLAs, get COLA details, search permittees, get permittee details, barcode lookup, and usage tracking. The same tools a developer would use, but invoked by an AI on your behalf.

One API key, everywhere

All four access methods — Python SDK, JavaScript SDK, CLI, and MCP — use the same API key. Generate one in the web app, and it works across all of them. Quotas are shared and metered in the same way regardless of which client you're using.

The blurring line between API and SQL

Something interesting is happening. The gap between "call an API" and "query a database" is getting smaller.

A SQL query might look like:

SELECT brand_name, product_name, approval_date
FROM colas
WHERE product_type = 'wine'
  AND origin = 'California'
  AND approval_date >= '2025-01-01'
ORDER BY approval_date DESC
LIMIT 20;

The CLI equivalent:

$ cola colas list --product-type wine --origin california \
    --date-from 2025-01-01 --limit 20 --json

And the MCP equivalent is just: "Show me California wines approved since January 2025."

These are the same question expressed three ways. The SQL version assumes you have database access and know the schema. The CLI assumes you have the tool installed and know the flags. The MCP version assumes nothing — you describe what you want and the AI figures out which tool calls to make.

For coding agents — tools like Claude Code, Cursor, Windsurf — this is a natural fit. An agent building an application that needs beverage data can discover the MCP tools, query for exactly what it needs, and integrate the results into whatever it's building. No documentation deep-dive required. The tool descriptions are the documentation.

Who uses which

In practice, the access methods tend to map to different workflows:

• SDKs for production applications and data pipelines where you want type safety, error handling, and pagination control
• CLI for ad-hoc exploration, quick lookups, and shell scripts
• MCP for AI-assisted development, conversational data exploration, and letting coding agents self-serve
• REST API directly, when you're in a language we don't have an SDK for yet, or you just prefer raw HTTP

The lines between these are blurry by design. A developer might start by asking Claude a question via MCP, get a feel for the data, then drop into the CLI to iterate on filters, and finally write SDK code for the production version. Same data, same auth, different interfaces for different moments.

Get started

Every plan includes API access, starting with 10,000 free records per month. The SDKs, CLI, and MCP server are all open source and documented at docs.colacloud.us.

Create a free account, generate an API key, and pick whichever access pattern fits your workflow.