ClearList for Developers & AI Agents

ClearList MCP Server

The ClearList MCP server exposes 24 tools (2 onboarding, 19 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.

• Manifest (scanner-friendly): https://clearlist.me/.well-known/mcp.json
• Server card (SEP-1649 canonical): https://clearlist.me/.well-known/mcp/server-card.json
• Source & install: github.com/Cuneiform-LLC/clearlist-mcp/tree/main/mcp-server
• Transport: stdio today; hosted HTTP/SSE planned post-Phase 14.

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.

• OpenAPI 3.1 specification: https://clearlist.me/.well-known/openapi.json
• Base URL: https://clearlist.me
• Standard response shape: { success: boolean, data?: T, error?: string }

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.

• Agent card: https://clearlist.me/.well-known/agent-card.json
• Agent skills index: https://clearlist.me/.well-known/agent-skills/index.json
• Individual skill documents (Markdown): /.well-known/agent-skills/<skill>/SKILL.md — currently create-and-publish-sale, bulk-upload, and manage-reservations.

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.

• Authorization server metadata: https://clearlist.me/.well-known/oauth-authorization-server
• Protected resource metadata: https://clearlist.me/.well-known/oauth-protected-resource

ClearList API Catalog & llms.txt

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

• API catalog (RFC 9727): https://clearlist.me/.well-known/api-catalog
• Plain-text product summary for LLMs: https://clearlist.me/llms.txt

Questions

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