DeskCafés API and MCP
Use https://deskcafes.com/mcp with a remote MCP client, or /api/external/v1 with an OAuth application.
Public discovery needs no account. Account access requires Authorization Code with PKCE S256 and deliberate user authorization. Tokens are bound to the selected resource: MCP tokens cannot call the API and API tokens cannot call MCP.
Every connection uses your current account and venue roles. Control access from Connected accounts in your profile. Credentials, authenticator secrets, passwords and codes are entered directly on protected DeskCafés pages.
Access tokens last 15 minutes. Rotating refresh tokens last 30 days. Keep credentials out of URLs and conversations. Send tokens only in the Authorization header. For repeated writes, retain the same request ID; use the current revision where required.
User-step operations return a protected link. They are not complete until the user finishes that action. Browser support for files, camera and Web Push varies.
Native Codex CLI requires version 0.147.0 or later to preserve the OAuth callback issuer; 0.160.0 is tested. Versions 0.145.0 and 0.146.0 can show “Authentication complete” in the browser and still reject the callback. Update the requesting CLI before another authorization. On Homebrew:brew update, then brew upgrade --cask codex. Verify codex --version and reuse the existing MCP configuration. A connection is confirmed by authenticated account use.
OpenAPI · Agent instructions · Privacy
| Operation | API | Access | Behavior |
|---|---|---|---|
search_venues | POST /venues/search | public | Search claimed, published venues; at most 25 venues per page. Prices are original amounts unless a display currency is selected. |
get_venue | GET /venues/{venueId} | public | Read a published venue, current offer, public reviews and eligible aggregates. This gives no seat guarantee. |
get_public_reviews | GET /venues/{venueId}/reviews | public | Read one bounded page of public venue reviews. |
get_public_profile | GET /profiles/{handle} | public | Read an opted-in public profile; private history remains unavailable. |
get_account | GET /me | account | Read the authenticated account's stable identifier and chosen profile. |
get_profile | GET /me/identity | account | Return the stable authenticated profile represented by verified credentials; its identity persists across refresh and reconnection. |
update_profile | PATCH /me/profile | account | Update chosen display name and handle. The existing 30-day handle-change rule still applies. |
update_biography | PATCH /me/biography | account | Update the biography using its current revision; conflicts never silently overwrite. |
update_history_privacy | PATCH /me/history-privacy | account | Set public-history visibility. Individual public reviews retain attribution. |
get_visits | GET /me/visits | account | Read the account's active visit and one page of its history. |
get_visit_quote | GET /venues/{venueId}/quote | account | Read current price, schedule, reward and non-binding conversion before preparing a visit. |
get_visit_code | GET /visit-codes/{tokenId} | account | Read a previously prepared visit code's state. Codes rotate every 30 seconds and expire within 90 seconds. |
validate_visit_code | POST /venues/{venueId}/visit-scans | account | Start or end a DeskCafes visit by validating the visitor's one-use code as authorized staff of that venue. This changes the visit and public activity count; closing may queue existing email or push notices and a review reminder. Reuse requestId for retries. No reservation, payment or paid status is created. |
get_venue_visits | GET /venues/{venueId}/visits | account | Read current visits as staff or permanent history as the venue administrator; current SQL roles determine visibility. |
get_venue_configuration | GET /venues/{venueId}/configuration | account | Read permitted configuration, revision, immutable source and current role. |
update_venue_pricing | PATCH /venues/{venueId}/pricing | account | Administrator updates original rate, payment methods and commercial/admission calendars using the current revision. |
get_my_venues | GET /me/venues | account | Read associated venues and pending claims. |
get_my_claims | GET /me/claims | account | Read one page of the account's claims and recoveries. |
get_venue_access | GET /venues/{venueId}/access | account | Read current permissions for the specified venue. |
get_staff | GET /venues/{venueId}/staff | account | Administrator reads current staff membership. |
search_staff | GET /venues/{venueId}/staff/search | account | Administrator finds registered accounts by public username. |
add_staff | POST /venues/{venueId}/staff | account | Administrator adds the selected registered account by username and queues the existing operational notice. |
remove_staff | DELETE /venues/{venueId}/staff/{staffId} | account | Administrator removes staff membership immediately. |
get_review_eligibility | GET /venues/{venueId}/review-editor | account | Read review eligibility and current editor/revision. |
save_review | POST /reviews | account | Publish or replace one living review after an eligible staff-closed visit; sanitized photos only. |
get_response_editor | GET /venues/{venueId}/reviews/{reviewId}/response-editor | account | Administrator reads a review-response editor and current revision. |
save_review_response | POST /review-responses | account | Administrator publishes or replaces the venue's response using its revision and request ID. |
get_referral | GET /referrals/{referralId} | account | Read an existing referral and reusable sharing link. |
get_my_referrals | GET /me/referrals | account | Read one page of the account's referrals. |
get_rewards | GET /me/rewards | account | Read one page of the account's referral rewards. |
clear_claim_referral | DELETE /claims/{claimId}/referral | account | Remove a referral selection from an account-owned pending claim. |
submit_staff_report | POST /reports/staff | account | Submit an immutable report to DeskCafes moderation about non-payment, session fraud or serious conduct during a closed visit you started or ended as venue staff. Requires your explicit report request, visitId, category and factual explanation. It is not a private draft or a sanction; any enforcement requires a separate human review. Reuse requestId for retries. |
submit_venue_report | POST /reports/venues | account | Submit an immutable report to DeskCafes moderation about a venue you visited, using the visitId, permitted category and your factual explanation. Eligibility and duplicate limits are checked. It does not delist the venue or decide the case; enforcement requires separate human review. Reuse requestId for retries. |
submit_content_report | POST /reports/content | account | Submit an immutable report to DeskCafes moderation about a published review or photo. Supply its target ID, category and factual explanation; an experience report also requires your eligible visitId. It is not a private draft and does not remove content or decide the case. Any enforcement requires separate human review. Reuse requestId for retries. |
get_report_status | GET /me/reports | account | Read only the requester's own report records, including accessible responses. |
get_media_status | GET /media/{assetId} | account | Read permitted asset processing state without exposing raw uploads or provider secrets. |
get_venue_album | GET /venues/{venueId}/album | account | Administrator reads the official album workspace and current revision. |
update_venue_album | PATCH /venues/{venueId}/album | account | Administrator reorders up to ten sanitized official photos with revision and idempotency protection. |
remove_photo | DELETE /media/{assetId} | account | Withdraw an account-owned or administrator-authorized photo through the existing cleanup pipeline. |
get_operation | GET /operations/{operationId} | account | Read a connection-owned pending operation without replaying a write. |
resume_operation | POST /operations/{operationId}/resume | account | Resume an operation after the user approves it on DeskCafes. QR secrets are returned once; retries return safe receipt metadata. |
get_claim | GET /claims/{claimId} | account | Read an account-owned claim and proof progress; source candidates are private. |
rotate_visit_code | POST /operations/{operationId}/visit-code | account | Rotate a previously user-approved start/end code after 30 seconds, preserving the accepted original price revision, reward and intent. Current SQL guards reject changed quotes and ended visits; no renewed authentication or model-generated acceptance is used. |
request_recovery_review | POST /recoveries/{recoveryId}/review-request | account | Ask a DeskCafes reviewer to examine a venue administration recovery affecting you as its previous administrator. Provide that recoveryId and your reason. The service checks ownership, eligibility and current authentication, and records the request once. This is not password recovery and does not reverse or approve the venue transfer. |
get_notifications | GET /me/notifications | account | Read current notification preferences. Web Push subscription requires the user's browser. |
disable_notifications | DELETE /me/notifications | account | Disable account Web Push delivery using the same preference service. |
get_upload_receipt | GET /media/uploads/{requestId} | account | Read an account-owned upload request's processing receipt. |
get_public_album | GET /venues/{venueId}/photos | public | Read the bounded public album of a published venue. |
update_venue_profile | PATCH /venues/{venueId}/profile | account | Edit ordinary venue description and contacts, preserving the existing staffed-public declaration; creating that declaration needs a protected user step. |
prepare_visit | POST /visit-codes | account | Prepare a start/end code after deliberate acceptance of the original rate on DeskCafes. Resume the returned operation after approval; staff must still validate the code. |
update_venue_characteristics | PATCH /venues/{venueId}/characteristics | account | Replace owner-declared resources and usage policies with revision validation. Published venues require all current answers; partial drafts remain unpublished. Reviews never alter these declarations. |
configure_venue | POST /venues/{venueId}/profile | account | Present a venue configuration and staffed-public declaration for deliberate user approval. |
publish_venue | POST /venues/{venueId}/publication | account | Request deliberate publication of a verified, configured venue. |
select_claim_referral | POST /claims/{claimId}/referral | account | Present the free-session referral obligation for deliberate acceptance. |
authorize_photo_upload | POST /media/upload-authorizations | account | Authorize a bounded original-byte upload for an account avatar, review or official album. Use the returned two-minute header capability with the exact upload URL; URL fetching is unsupported. |
lookup_overture | POST /claims/lookup | account | Open the protected DeskCafes venue search when you want to claim a venue, refer one or recover its administration. Choose purpose claim, referral or recovery. Returns a user_action_required link and operationId; the user completes CAPTCHA and the bounded search on DeskCafes. Candidate results are private, not the published venue catalogue. Existing search quotas apply. |
select_overture | POST /claims/selections | account | Select a venue candidate returned by your completed private DeskCafes search to create or reuse a claim, administration recovery or referral link. Supply the exact sealed receipt and matching purpose from that search; receipts are bound to your account and session. Selection does not establish ownership, publish the venue or bypass control verification. |
begin_domain_proof | POST /claims/{claimId}/domain-proofs | account | Prepare DNS or HTTPS control proof from the claim's verified official contact; no arbitrary network target is accepted. |
check_domain_proof | POST /proofs/{proofId}/check | account | Check a prepared DNS/HTTPS control proof with current account, owner, nonce, provider bounds and SQL revalidation. |
start_sign_in | POST /auth/start | public | Start account login, registration or email recovery in a protected DeskCafes surface. |
complete_onboarding | POST /me/onboarding | account | Complete chosen identity, adult declaration, Terms and mobile verification in DeskCafes. |
manage_password | POST /me/password | account | Change or recover a password directly in DeskCafes; never send passwords to this tool. |
manage_phone | POST /me/phone | account | Verify or replace the phone directly in DeskCafes; SMS requests remain deliberate. |
manage_google | POST /me/google | account | Manage Google access directly in DeskCafes, retaining fresh email and password proof before unlink. |
manage_totp | POST /me/totp | account | Manage optional login TOTP in DeskCafes. Never send authentication codes, setup seeds or recovery codes to an agent. |
export_account | POST /me/export | account | Request the existing protected account export including integrations. |
delete_account | POST /me/deletion | account | Open the deliberate protected account deletion with real recent authentication. |
manage_notifications | POST /me/notifications | account | Manage preferences and grant Web Push permission in a compatible browser. |
request_reconsideration | POST /reconsiderations | public | Open the DeskCafes appeal form when you want review of a moderation decision about your account, venue or content. Returns a protected URL, not a submitted appeal. Enter the decision ID, reason and email verification directly on DeskCafes and complete its CAPTCHA; never send email codes to the agent. Eligibility is checked there, and opening the form does not reverse the decision. |
submit_illegal_notice | POST /illegal-notices | public | Submit a deliberate public illegal-content notice with the existing CAPTCHA and good-faith declaration. |
delete_venue | POST /venues/{venueId}/deletion | account | Delete a venue with deliberate confirmation and actual recent authentication. |
manage_control_proof | POST /claims/{claimId}/proof | account | Complete email/SMS/voice/domain control proof. Codes and paid sends are handled directly in DeskCafes. |
upload_photo | POST /media/uploads | account | Upload original image bytes directly to the existing sanitizer; arbitrary remote URLs are never fetched. |
Platform directory listings and platform verification are separate from this server’s protocol support. No directory listing is implied.