This is the reference page. If you want the story of why ClearList is built this way, that is a different post. If you want to know what the tools are and what they do, you are in the right place.
The server is a thin protocol adapter. Every tool calls the same /api/* route the web app calls, which means there is no separate agent codebase that can drift out of sync with the product. If the UI can do it, the API can do it, and the tool is a wrapper over that.
Connecting
Remote endpoint:
https://clearlist.me/api/mcp
Add that as a connector in Claude or ChatGPT and the tools appear in your next conversation.
For local or scripted use, there is an npm package:
npm install -g @clearlist/mcp-server
It is published under two names, @clearlist/mcp-server and the unscoped clearlist. Point it at https://clearlist.me with CLEARLIST_API_URL and it speaks stdio.
Authentication
This is the part most likely to trip you up, because the two transports authenticate differently.
Hosted endpoint (/api/mcp): OAuth. Every request requires a valid credential. There is no anonymous bootstrap. Add the connector in Claude or ChatGPT, and the client runs a standard OAuth 2.1 authorization-code flow with PKCE. You will be sent to a consent screen, and if you are not already signed in, to /login first. Login itself is still passwordless (email plus a 6-digit code), but it happens in a browser, not in the chat. Clients register dynamically via the registration endpoint, or use a Client ID Metadata Document.
A request without a credential returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which is how the connector discovers where to authenticate.
npm/stdio package: email-OTP, fully in-conversation. This is the path where the onboarding tools work anonymously. You call send_verification_code with an email, ClearList sends a 6-digit code, and verify_code with agent: true returns a key. No browser at any point.
Keys are formatted cl_ plus 64 hex characters, sent as X-ClearList-API-Key, stored SHA-256 hashed so the raw key is never kept. Lifetime is tied to your plan, and an expired key returns 401 rather than failing quietly.
Discovery metadata, if your client looks for it: the OpenAPI 3.1 spec is at /.well-known/openapi.json, the MCP manifest at /.well-known/mcp.json, the server card at /.well-known/mcp/server-card.json, and the auth guide at /auth.md.
Onboarding tools (2)
These two work without an API key on the stdio transport only. Over the hosted endpoint they sit behind the same auth gate as everything else, because OAuth replaces that bootstrap there.
| Tool | What it does |
|---|---|
send_verification_code | Emails a 6-digit code to the address you supply |
verify_code | Verifies the code, creates the account if it is new, and returns an API key |
Seller tools (19)
Everything below requires a key.
Creating and editing listings
| Tool | What it does | Route |
|---|---|---|
create_listing | Photos in, AI listing out, saved | multi-step |
bulk_create_listings | Up to 50 photos, grouped by item, all listed | multi-step |
edit_listing | Update any field on an item | PUT /api/items/[id] |
delete_listing | Soft-delete, restorable for 7 days | DELETE /api/items/[id] |
restore_listing | Undo a delete inside the window | POST /api/items/[id]/restore |
mark_picked_up | Set an item to taken | PUT /api/items/[id] |
The sale page
| Tool | What it does | Route |
|---|---|---|
publish_page | Publish the sale page, return its URL | POST /api/pages/publish |
unpublish_page | Take it offline. Existing reservations continue; only new visits are blocked | POST /api/pages/unpublish |
get_listings | All items with current status | GET /api/items |
get_page_stats | Views, item count, reservation count | GET /api/pages/[slug]?stats_only=true |
Buyers
| Tool | What it does | Route |
|---|---|---|
get_reservations | Who reserved what, queue positions, timer status, messages | GET /api/conversations |
get_conversation | Read a single thread | GET /api/conversations/[id] |
reply_to_buyer | Send a message to a buyer | POST /api/conversations/[id] |
confirm_pickup | Confirm a pickup happened, mark those items sold | POST /api/reservations/[id]/pickup-confirm |
Scheduling, money, and the rest
| Tool | What it does | Route |
|---|---|---|
set_availability | Configure pickup windows and slot length | PUT /api/scheduling/availability |
generate_payment_link | Return a Stripe checkout URL for an upgrade | POST /api/payments/checkout-link |
check_tier_status | Plan, remaining capacity, expiry | GET /api/payments/status |
get_profile | Tier plus a listings overview | combines two routes |
prepare_crosspost | Listing text formatted for other platforms | GET /api/crosspost/prepare |
That last one exists because Facebook Marketplace has no public listing API. Nothing can post there for you, so the useful thing is to hand you text that is ready to paste.
Discovery tools (3)
These are stubs. They return NOT_IMPLEMENTED and say so, because a tool that silently returns nothing is worse than one that admits it is not built yet.
| Tool | Status |
|---|---|
search_items | Phase 14 |
get_sales_near | Phase 14 |
get_city_sales | Phase 14 |
They are registered rather than hidden so that agents can discover the shape of what is coming and fail loudly instead of silently.
The tool that is not there
There is no share_address.
Not a restricted version, not one behind a confirmation prompt. It does not exist, and no API route reaches a seller's address with agent credentials.
The reasoning is short. Someone who wants to find a person can recognize a couch in a listing photo and message the seller as an interested buyer, and the whole thing looks like an ordinary sale until it is not. A confirmation dialog does not fix that, because if an agent can be argued into disclosing an address then some phrasing exists that argues it into disclosing an address.
So it lives in the first-party app, done by the signed-in seller, and there are security tests pinning that in place. They assert that the address route refuses an API-key credential with a 403 without ever authenticating it, that the refusal does not leak the address back in its own error, that a first-party session still reaches auth normally, and that the MCP surface exposes no share_address tool at all.
For reference purposes: it is absent on purpose, and it is the only thing in the product an agent cannot reach.
Counts, for anyone checking
Two onboarding, nineteen seller, three discovery stubs. Twenty-four total. If you are reading a doc somewhere that says a different number, count the registerTool calls in mcp-server/src and trust those instead. Documentation drifts. Source does not.
More for developers: clearlist.me/developers and the API docs.