CLI, MCP and SDK Access

COLA Cloud now has four public access paths: Python, JavaScript, a terminal CLI, and MCP for AI assistants. They all hit the same API, share the same quotas, and return the same underlying data.

The point is not to make everyone use all four. The point is to meet the workflow you're already in.

The Python SDK

Install with pip install colacloud. Works with Python 3.10+, supports both sync and async clients, and ships type hints so your editor can catch mistakes before the API does.

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}")

For larger pulls, use the iterator and let the SDK handle pagination:

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}`);
}

TypeScript support is built in. 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 is the interface I want when opening a notebook would be too much ceremony.

The MCP server

This is the newest addition. 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 Claude Code, or any MCP client that supports remote HTTP servers with headers:

{
  "mcpServers": {
    "colacloud": {
      "type": "http",
      "url": "https://mcp.colacloud.us/mcp",
      "headers": {
        "Authorization": "Bearer ${COLA_API_KEY}"
      }
    }
  }
}

Then ask normal questions:

• "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 API endpoints, handles pagination, and formats the answer. The current MCP surface includes assistant-friendly search/fetch tools, COLA and permittee lookups, barcode lookup, usage tracking, TTB reference-data tools, and durable saved-search creation. It is the same data surface a developer would use, invoked by an assistant instead of by your code.

One API key, everywhere

All four access methods — Python SDK, JavaScript SDK, CLI, and MCP — use the same API key. The setup docs cover key creation and authentication, and the key works across all of them. Quotas are shared and metered the same way regardless of client.

The blurring line between API and SQL

The line between "call an API" and "query a database" is getting less crisp.

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. SQL assumes database access and schema knowledge. The CLI assumes you know the command shape. MCP assumes you can describe the question and let the assistant choose the tool call.

For coding agents — tools like Claude Code, Cursor, Windsurf — that is the useful part. An agent building an application can discover the MCP tools, query for the beverage data it needs, and keep working without making you stop and translate the request into HTTP.

Who uses which

Roughly, the access methods map to different jobs:

• 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 on purpose. 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 interface.

Get started

Every plan includes API access to 2015-forward records, starting with 10,000 free list records per month. The SDKs and CLI are open source, and the MCP server is documented at docs.colacloud.us.

Start with the docs, then use whichever interface fits the job.