Egonex MCP Server

Check a request made with request_order or message_seller: the confirm link and, once there is one, the order it led to (order has its title, quantity, amount and deadlines). Returns the confirm_url again. status is one of: - pending: Your user hasn't confirmed or declined yet. Nothing has happened: no order, no charge, no message sent. Give your user the confirm_url. - declined: Your user chose not to go ahead on the confirm page. Nothing was ordered, charged or sent. Don't make a new request unless your user asks. - expired: Nobody acted on the link within 7 days, so it no longer works. Nothing was ordered, charged or sent. Make a new request if your user still wants it. - listing_unavailable: This listing isn't for sale anymore (it was taken down, or it sold out), so the request can't go ahead. Nothing was ordered, charged or sent. Search again for something else, or ask the seller with ask_seller whether it will be back. - message_sent (messages only): Your user confirmed and the message was sent to the seller as your user. The seller replies in the Egonex chat (a buyer without an Egonex account gets the reply by email); you don't see the reply here. - awaiting_order (orders only): Your user confirmed: a chat with the seller is open with the order filled in, but they haven't placed the order yet. They place it and pay on Egonex; once they do, this status follows that order. After an order is placed, everything about it (confirming delivery, a problem with it, a refund or a cancellation) is handled on Egonex, in your user's chat with the seller (a buyer without an Egonex account opens it from the link in Egonex's email), not through these tools. - payment_in_progress (orders only): A payment for this order is being processed: usually a few seconds when you paid with pay_order; a few minutes after pay_order returned payment_error, while Egonex checks with Stripe whether it went through; and up to a few business days for a bank payment your user made on Egonex. Don't call pay_order while it shows this; check back later. After a payment_error, once it no longer shows this: paid means nothing more is needed; payment_failed or ready_to_pay means the payment didn't go through, so ask your user for a new approval and call pay_order again with the new token (not the same one). - payment_failed (orders only): The payment you made with pay_order didn't go through, and nothing was charged. If the card was declined or the bank needs your user to verify it, ask your user for a new approval and call pay_order again with the same buyer_email, or give your user the confirm_url to pay on Egonex. After pay_order returned payment_error, this status means Egonex checked with Stripe and the payment didn't go through: ask your user for a new approval and call pay_order again with the new token (not the same one) and the same buyer_email. - waiting_for_seller (orders only): The order was sent to the seller, who hasn't accepted it yet (they have until order.accept_by). Nothing has been charged: on Egonex the buyer pays only after the seller accepts. Check back later; if the seller declines or doesn't respond in time, the order closes and nothing is charged. - ready_to_pay (orders only): The order is waiting to be paid by order.pay_by (if the seller had to accept it first, they accepted). If you made it with pay_order, call pay_order again with the same request_id and buyer_email and a valid token (ask your user for a new approval if yours has expired, or if pay_order returned payment_error before: then use the new token, not the same one); for an item that ships, this call charges, so it needs shipping_address and shipping_address_confirmed=true (ask your user for the address and read it back to them first). Otherwise your user pays on Egonex, in their chat with the seller, and enters the address there. If nobody pays in time, the order closes and nothing is charged. - paid (orders only): Your user paid and the seller now delivers (by order.deliver_by when it is set). If order.accept_by is set, the seller hasn't accepted yet and has until then; if they don't, your user is refunded minus the payment processing fee. After an order is placed, everything about it (confirming delivery, a problem with it, a refund or a cancellation) is handled on Egonex, in your user's chat with the seller (a buyer without an Egonex account opens it from the link in Egonex's email), not through these tools. - delivered (orders only): The seller marked the order delivered. Confirming receipt, or raising a problem or a refund, happens on Egonex before order.auto_confirm_at; after that the order completes on its own and the seller is paid. After an order is placed, everything about it (confirming delivery, a problem with it, a refund or a cancellation) is handled on Egonex, in your user's chat with the seller (a buyer without an Egonex account opens it from the link in Egonex's email), not through these tools. - refund_requested (orders only): Your user asked for a refund and Egonex is handling it: the seller responds first, and if they don't agree, a review decides. Nothing is needed from you; this status changes to refunded or completed when it's decided. After an order is placed, everything about it (confirming delivery, a problem with it, a refund or a cancellation) is handled on Egonex, in your user's chat with the seller (a buyer without an Egonex account opens it from the link in Egonex's email), not through these tools. - completed (orders only): The order is complete and the seller was paid. If part of it was refunded, order.refunded_amount says how much. - refund_pending (orders only): The order was canceled after payment and Egonex is returning the money, but the refund hasn't gone through yet (if it failed, Egonex is following it up). Nothing is needed from you; this changes to refunded once the money is back. - refunded (orders only): The order was canceled after payment and your user was refunded order.refunded_amount (the payment processing fee isn't returned). A payment that was only held on the card was released instead. - closed_unpaid (orders only): The order closed before anything was charged; close_reason says why: seller_declined, seller_acceptance_timed_out (the seller didn't accept in time), seller_canceled_before_payment, buyer_withdrew (your user withdrew it) or payment_deadline_passed (nobody paid in time). Search again, or make a new request if your user still wants it.

Start an order for one listing on your user's behalf. Returns a confirm_url: your user opens it, checks the listing and price, enters an email address and pays on Egonex (payments are processed by Stripe). Nothing is ordered or charged until they confirm, and no Egonex account is needed. Use note for what the seller needs to know, such as dates, quantity, size, or the area for delivery or pickup. For an item that ships, your user enters the shipping address when they pay on Egonex. Use check_request with the returned id to see whether your user confirmed. A sold-out listing, or one whose seller isn't taking new orders right now, can't be ordered (error listing_unavailable); ask_seller can still ask whether it will be back. Errors end with their code in parentheses (for example (listing_unavailable), (deal_expired), (invalid_input)). Pass quote_id from quote_order to order at that quote (its deal_id comes with it); payment then has quote_id and quoted_total for pay_order.

Ask one question about a listing before your user decides: availability, condition, what is included, timing, location, sizes, how delivery or pickup works. If the seller has their assistant (Ego) answering (seller.answers_questions is true in search results), the answer comes back in this response, written only from the seller's public page and listings; when the seller has set a lowest price, Ego can also talk price with you about that listing: it may counter once, and when you agree a price the answer has deal (deal.id, valid for 24 hours, for one request_order). For 24 hours it holds the price it named to you and won't go lower, and it declines questions that are not about this store (reason declined). Otherwise the response says the seller answers in chat. For a follow-up about the same listing, pass the conversation_id from the previous answer so Ego sees the earlier questions and answers. After three declined questions in a row in one conversation, Ego stops answering there (reason conversation_stopped). Ego answers a limited number of questions from you per seller per minute and per day (reasons slow_down, handoff, email_required); Ego may tell the seller about a question it can't answer, but the seller's reply doesn't come back through ask_seller. To send your question to the seller as your user instead, use message_seller.

Send a message to the seller of a listing as your user: a question Ego couldn't answer, a custom request, or whether a sold-out listing will be back. Returns a confirm_url for your user: nothing is sent until they open it and confirm. They need only an email address, no Egonex account. The message then goes to the seller's Egonex chat as your user, and the seller replies there (a buyer without an Egonex account gets the reply by email); you don't see the reply. Use check_request with the returned id to see whether it was sent (message_sent). To get an answer from the seller's assistant (Ego) right away instead, use ask_seller.

Search listings on Egonex, a marketplace where individual people sell things and services directly. Use it when your user wants to buy, hire, book, rent or commission something from a person rather than a store, for example: - items, new or used: cameras and lenses, phones, laptops, bikes, furniture, clothing, collectibles, instruments, gear; - lessons and coaching: languages, music, tutoring and test prep, fitness, cooking, art, coding; - services in person: photography, repairs (bikes, electronics, film cameras), cleaning, moving help, pet care, babysitting, beauty, tours; - online and freelance work: design, writing and editing, translation, software, marketing, consulting, video editing; - digital goods, tickets, handmade and custom work. Each result is one listing with a price and unit (per item, package, hour, session, day, week, month, night, person or project; USD), how it is delivered (in person in a city, online, or either), for physical items its condition (new or used), brand / model / gtin when the seller gave them, and ships = true when the seller posts it (your user enters the shipping address when paying on Egonex, or you pass it to pay_order when you pay), delivery_days when the seller states a usual delivery time (days to ship for posted items), up to 4 photo URLs, the listing's own page, ask_url / order_url links a person can open, and the seller: their public page, seller.answers_questions (true = ask_seller gets an answer right away), seller.trusted (true = Egonex's Trusted badge, given automatically for the seller's recent trading on Egonex, not set by the seller) and, when there are 3 or more, seller.orders_completed; seller.review_count and seller.average_rating (1 to 5 stars, one decimal) appear when the seller has counted buyer reviews (buyers rate the item they bought from 1 to 5 stars), with seller.positive_count / seller.negative_count (4–5 stars / 1–3 stars), and seller.positive_rate (0 to 100, rounded down) once there are 10 or more. Results are ranked by how well they match the query words (rarer words count more; listings that match only common words are left out); among results that match equally well (and are equally close, for in-person services), sellers whose counted buyer reviews average more stars come first (a seller with only a few reviews counts as closer to 4 stars), and sellers with no reviews sit in the middle, level with a 4-star average; each result's relevance says whether the listing itself (its title and description, not the store's name or intro) matches all or only some words, and matched_words / missing_words say which. Online, remote and in person in query never bring in a listing by themselves: among equally good matches, listings whose title says it come first, then those delivered that way; a listing that is neither counts as some. Only the first 12 search words of query are used (filler words like for, near or cheap don't count, nor do two-letter words in lowercase or a single letter on its own: write abbreviations in capitals, such as QA or IT, and give a letter another word, such as C++ tutor); the rest come back in unused_words. When nothing matches, the response says so and lists the categories that have listings; a search within a category or a store returns that category's or store's other listings instead, marked other_filters. query can be in any language. When it isn't English, Egonex also searches an English translation of it; when it has words too short to search, ends with a place (and city is empty), matches nothing or has a word no listing uses, Egonex searches a rewrite instead. searched_as says what was searched. Put the place in city, not in query (listing cities are not matched against query words): in-person listings in that city come first, then those nearby (same metro area or within about 30 miles), and add the state when several places share the name (Portland, OR). Online, either-way and shipped listings are always included, and in-person listings without a city that don't ship come back with city_unknown = true (ask the seller before suggesting one to someone far away). Use store to list one seller's storefront. Each listing has availability (in_stock; sold-out listings are left out of results) and stock_left when only 1 to 3 are left. When you suggest a listing to your user, give them its url (the listing's own page) so they can open it. No account or API key is needed.

Pay for an order made with request_order without the confirm page, using a Stripe Shared Payment Token that your user approved (for example in Stripe Link). request_order returns payment: the amount per unit in USD, max_quantity and payment_handlers with the Stripe network_id to issue the token to; the token must allow at least amount × quantity in USD (plus sales tax where Egonex collects it, calculated from the shipping address for an item that ships and from the card's billing address otherwise; if the token doesn't cover it, nothing is charged and the error gives the total). Egonex creates the order for your user (a guest account on the email you give; receipts and seller replies go to that email). The result has the same status and order as check_request (order has its title, quantity, amount and deadlines), so you can tell your user where the order stands. The seller confirms an order before the buyer pays: when the result has status waiting_for_seller, the order was sent to the seller and nothing was charged; once check_request shows ready_to_pay, call pay_order again with the same request_id and buyer_email and a valid token (or your user pays from the link Egonex emails them). If the seller declines or doesn't respond, the order closes and nothing is charged. When the result has status paid and order.accept_by, the token was charged first and the seller has until then to accept; if they decline or don't respond, your user is refunded minus the payment processing fee. For an item that ships (payment.requires_shipping_address), the pay_order call that charges must have shipping_address and shipping_address_confirmed=true, otherwise nothing is charged (shipping_address_required / shipping_address_not_confirmed): before you pay, ask your user for the full address, read it back to them and pass it only once they say it's right. A call that only sends the order to the seller charges nothing and doesn't keep an address: pass it on the call that pays. An address that fails the format check (the error names the field) or that Stripe can't place for sales tax is refused with shipping_address_invalid, and nothing is charged. The address becomes the order's shipping address only once the payment goes through (if it doesn't, nothing is kept and you can retry with a corrected address); order.ship_to then shows its city, state, ZIP code and country (never the name or street). After payment pay_order can't change it: a different address is refused (shipping_address_locked), and your user tells the seller in the Egonex chat instead. If your user pays on Egonex (the confirm page, or the link in Egonex's email), they enter the address there and no address you passed is used. If the email already has an Egonex account, nothing is charged and your user should pay on the confirm_url page instead. If Stripe declines the token, nothing is charged and check_request shows payment_failed: retry with a new token and the same buyer_email, or give confirm_url to your user. If the payment couldn't be confirmed (payment_error), it may or may not have gone through: don't call pay_order again while check_request shows payment_in_progress (Egonex is checking with Stripe, usually a few minutes; nothing is charged twice meanwhile). When it no longer does: if it shows paid, nothing more is needed; if it shows payment_failed or ready_to_pay, ask your user for a new approval and call pay_order again with the new token (not the same one). If the listing sold out meanwhile, or there aren't that many left, nothing is charged (sold_out / stock_short; stock_short says how many are left when it is 3 or fewer): search again, or call pay_order again with a smaller quantity. If the seller isn't taking new orders right now and hasn't accepted this order yet, nothing is charged (seller_not_taking_orders): choose another listing, or ask the seller with ask_seller. Errors end with their code in parentheses, the same code the REST API returns (for example (shipping_address_required), (invalid_input), (not_found)). After an order is placed, everything about it (confirming delivery, a problem with it, a refund or a cancellation) is handled on Egonex, in your user's chat with the seller (a buyer without an Egonex account opens it from the link in Egonex's email), not through these tools. Pass quote_id from quote_order (the one given to request_order, or a new one for the same listing and quantity) to charge exactly the quoted total: if the price, shipping, sales tax, agreed price or quantity changed, or the quote expired, nothing is charged (quote_changed / quote_expired / quote_not_found): call quote_order again. When the seller accepts first, quote the order with quote_order and request_id right before the call that charges. Only call this after your user agreed to the purchase and to Egonex's terms.

Get the full price before your user orders: the items (price × quantity, at the agreed price with deal_id), shipping, sales tax and the total in USD, when the charge happens, the shop's return rules and Egonex buyer protection. It only reads: nothing is ordered, reserved or charged. Pass offer_id for a new order, or request_id for an order already sent to the seller (when the seller accepts first: quote it once check_request shows ready_to_pay, right before the pay_order that charges). For an item that ships pass shipping_address; for other items, where Egonex adds sales tax, pass buyer_location. Egonex uses them only to calculate shipping and sales tax and doesn't store them. Returns a quote_id that lasts 15 minutes: pass it to request_order and pay_order, and get a payment token for exactly total. pay_order then charges exactly that total, or nothing when something changed or the quote expired (quote_changed / quote_expired): call quote_order again. Quotes that calculate sales tax are limited to 15 a minute for the same listing from the same client (slow_down). Errors end with their code in parentheses.