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 and the tools appear in your next conversation. Any MCP host that can run an OAuth flow works the same way.
ChatGPT is the exception, and it is worth being precise about why. As of August 2026, adding your own connector there is a Business and Enterprise/Edu feature that a workspace admin has to enable, and it only works on the web. A personal Plus or Pro account cannot do it at all. Consumer access arrives through the ChatGPT Plugin Directory, where our listing is in review.
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, 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 (23)
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 |
create_upload_session | Mints a phone upload link, so a host that cannot attach files still gets full-resolution photos | POST /api/upload-sessions |
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 |
extend_sale_page | Keep an expiring page live. Free where the tier allows it, otherwise it returns the purchase options | POST /api/pages/extend |
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] |
share_address | Step 1 of sharing an address. Sends nothing to the buyer | POST /api/conversations/[id]/address/prepare |
confirm_address_share | Step 2. Sends it. Irreversible | POST /api/conversations/[id]/address |
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 takes two calls
Sharing an address is the one action here that an agent cannot complete on its own, and the split is visible in the tool list.
| Tool | What it does |
|---|---|
share_address | Sends nothing to the buyer. Looks up who would receive the address, freezes the exact string, and returns the recipient, the address and a confirmation token to the seller's side of the conversation. |
confirm_address_share | Sends it. Irreversible. |
The point of freezing the address at step one is that the seller approves a specific string going to a specific person. If the second call could carry its own address, the confirmation would be approving one thing while the system sent another.
Four things hold this in place, and the fourth is the one doing the most work.
An API key arriving without a valid token is refused. A token names its own conversation, works once, and expires after ten minutes. Only a buyer who verified their email by reserving something can receive an address, so an enquiry alone is refused. And the seller is emailed a record of every share, sent by the server after the fact, naming the buyer and containing the address that went out.
What is NOT a boundary, stated plainly because it is the thing people assume: the Approve button. The server sees the same API key whether a human tapped it or a model called the tool. The controls above are the ones that do not depend on a model behaving.
This used to say there was no such tool at all. Here is what changed and why.
Counts, for anyone checking
Two onboarding, twenty-three seller, three discovery stubs. Twenty-eight 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.