Back to home

ClearList for Developers & AI Agents

Every action a ClearList seller can take in the web app is also available to AI agents and external integrations.

ClearList ships with a Model Context Protocol (MCP) server, a REST API, an OpenAPI 3.1 specification, and an agent-card manifest. Connect Claude, ChatGPT agent mode, Codex CLI, Google Antigravity, or any other MCP client. No scraping, no reverse engineering, no private deals required.

Not a developer? See how to connect ClearList to Claude.

ClearList MCP Server

The ClearList MCP server exposes 28 tools (2 onboarding, 23 seller actions, 3 discovery stubs) covering listing creation, sale page publishing, reservation management, buyer messaging, pickup scheduling, and payment links. It is a thin protocol adapter over the REST API — anything the web UI can do, the MCP server can do.

Agent Skill (one command)

The shortest path. One command installs a skill that teaches your agent the entire ClearList flow, including how to set up the MCP server below, so most people need nothing else. It follows the Agent Skills specification, so the same file works in Claude Code, Codex, Gemini CLI, GitHub Copilot, and Antigravity. That is the list of Agent Skills hosts, which is not the same as the list of MCP hosts below.

npx skills add Cuneiform-LLC/clearlist-mcp

ClearList CLI

The npm package also installs a clearlist command-line tool for scripting seller actions without an MCP host: log in with an email code, list items, publish the sale page, read reservations, and reply to buyers. Every command prints JSON, so output pipes cleanly into scripts.

  • Install: npm install -g @clearlist/mcp-server
  • Usage: clearlist login you@example.com → clearlist verify you@example.com <code> → clearlist items
  • Reference: npmjs.com/package/@clearlist/mcp-server

ClearList REST API

The same REST routes the web UI calls. Every seller action goes through /api/* — there are no client-only Firestore writes — so agents can do everything sellers can do.

ClearList Agent Card & Skills

Machine-readable metadata describing the ClearList agent and the specific tasks it supports. AI agents that follow the agent-card convention can discover ClearList capabilities without reading documentation.

ClearList Authentication

ClearList accepts two credentials. Firebase ID tokens are for the web UI; ClearList API keys are for agents. Both are processed by the same auth pipeline.

For agents: ClearList API key

  • Header: X-ClearList-API-Key: cl_<64_hex_chars>
  • Keys are SHA-256 hashed at rest. The raw key is shown once at issuance and never stored.
  • TTL is tied to the seller's tier: free 30 days, Move Sale 30 days, Garage Sale 60 days.

Agent onboarding (no UI required)

  1. Agent calls send_verification_code with the seller's email.
  2. Seller reads the 6-digit code from their inbox.
  3. Agent calls verify_code with { email, code, agent: true }. ClearList creates the account if needed and returns an API key.
  4. Agent stores the key and calls all subsequent endpoints with the X-ClearList-API-Key header.

ClearList OAuth Metadata

ClearList publishes RFC 8414 OAuth 2.0 Authorization Server Metadata and RFC 9728 Protected Resource Metadata so agents that prefer OAuth-style discovery can negotiate scopes programmatically. For most agents the API key flow above is simpler.

ClearList API Catalog & llms.txt

For AI crawlers and search engines that want a one-stop summary of every machine-readable surface ClearList offers.

Questions

For integration questions or to report broken endpoints, email hello@clearlist.me.