#MCP Tools — Using ambientChat with Claude Desktop

Your AI context doesn't have to stay trapped inside one app. With MCP (Model Context Protocol), you can bring your entire ambientChat world into Claude Desktop, brand apps, or any compatible AI client — and it works exactly like having a very well-informed research assistant sitting at your desk.

All tools respect your authentication. The AI can only access your data, using your credentials. Nobody else's stuff, ever.

#Inventory Tools

Manage your physical items — everything you've scanned, photographed, or manually added.

Tool What It Does
list_items List all items, optionally filtered by category, folder, or search query
get_item Get full details of a specific item — name, brand, price, expiry, location, notes, nutritional data
search_items Semantic search — finds items by meaning, not just keywords ("things in my garage", "snacks for the party")
list_expiring_items Find items expiring within a number of days (default 14). Set include_expired to also see items already past their date
get_items_at_scene List items last seen at a specific physical location — identified by beacon, GLN, or scene ID
get_scan_session_items List items created together in the same scan session (scan siblings)
update_item Edit any item field — name, brand, category, price, expiry date, location, notes
update_items_by_filter Bulk-update fields across many items in one call. Say "change all items in the kitchen to category Food"
trash_item Move a single item to trash (soft delete). Cleans up linked documents
trash_items Bulk move multiple items to trash at once
restore_item Restore an item from trash back to the inventory
regenerate_item_image Generate a fresh AI illustration for an item. Costs credits

Example things you can say:

  • "What's in my pantry?"
  • "Show me everything expiring this week."
  • "Change the category of all my vitamins to Health."
  • "How much is my electronics collection worth?"
  • "What was scanned with the olive oil?" (scan siblings)
  • "What did I leave in the garage?" (items at scene)

#Document Tools

Navigate, search, and manage your digital paperwork — receipts, manuals, photos, and files.

Tool What It Does
list_documents List documents with optional filters for media type, category, and folder
get_document Get full document details — AI summary, linked items, metadata
search_documents Keyword search across document titles, summaries, and content
search_documents_semantic AI-powered semantic search — finds documents by meaning, returns full content
update_document Update a document's title, description, and/or tags. Improves search and accessibility
upload_document Upload a new document (image or PDF) into a folder for AI processing. Provide the bytes one of three ways: a Firebase Storage URL, a get_document_upload_url storage path, or inline base64 (max 10MB)
get_document_upload_url Get a short-lived signed URL for uploading document bytes directly to storage, then hand the returned path to upload_document. This is how an AI client that holds a file (e.g. one with a code-execution sandbox) gets it into a folder without inlining the bytes
get_scan_status Check the status of an upload/scan job by its jobId (returned by upload_document). Tells you whether it's still processing, complete (with the created document/item), or failed (with the reason) — so you don't have to keep refreshing the folder
move_document Move a document between folders
trash_document Move a document to trash (soft delete). Cleans up linked inventory items
restore_document Restore a document from trash
regenerate_document_image Generate an AI illustration thumbnail for a document. Costs credits

Example things you can say:

  • "Find my Costco receipts from January."
  • "Show me all my warranty documents."
  • "Move the washing machine manual to the Appliances folder."
  • "What receipts do I have for tax deductions?"
  • "Save these photos into my Medical folder." (uploads the attached images for processing)
  • "Did that upload finish?" (checks the upload job's status)

#Views (Folders)

Organize your items and documents into folders and views.

Tool What It Does
list_views List folders at a given level of the hierarchy
get_view Get folder details and its first 20 documents
get_view_tree See the entire folder hierarchy at a glance, with item, document, and subfolder counts
get_view_members Get the union of items and documents in a folder
create_view Create a new folder. Idempotent — won't create duplicates
update_view Rename a folder, change its description, sort order, or thumbnail mode
reorder_views Batch update the sort order for multiple folders
generate_view_icon Generate an AI icon for a folder based on its name and contents. Costs credits
add_items_to_view Tag items with a folder — adds them without removing prior folder memberships
move_items_to_view Move items to a single destination folder
remove_items_from_view Remove items from a folder
navigate_up Navigate to the parent folder

Example things you can say:

  • "Create a folder called Holiday Gifts."
  • "Move all the spices into the Spice Rack folder."
  • "How many items are in each folder?"
  • "Generate an icon for the Kitchen folder."

#Markdown Documents

Create, edit, and search your own written documents — notes, lists, reports, and more.

Tool What It Does
create_markdown_document Create a new markdown document with optional YAML frontmatter and folder placement
update_markdown_document Update a document — replace the full content, or target a specific section by heading
get_markdown_document Retrieve a document's full content, parsed frontmatter, table of contents, and version info
list_markdown_documents List markdown documents, optionally filtered by folder, type, or tags
search_markdown_content Semantic + keyword search across markdown document content
create_office_document Generate a Microsoft Office file (Excel .xlsx, Word .docx, or PowerPoint .pptx) from content and save it to your library with a download link

Example things you can say:

  • "Create a packing list for my Hawaii trip."
  • "Make a spreadsheet of everything expiring this month." → create_office_document
  • "Write a summary of what I bought this month."
  • "Update the recipes section of my meal plan."
  • "Find my notes about home insurance."

#Skills

First-party skills are reusable SKILL.md playbooks — curated by ambientChat — that orchestrate your inventory, documents, tags, location, and beacons. They're available to everyone (read-only); follow a skill's steps to get a repeatable result, and the same skills work in Claude and ChatGPT when you connect ambientChat there.

Tool What It Does
list_skills List the available first-party skills with their name, slug, and description
get_skill Load a skill's full instructions (SKILL.md) by slug, ready to follow

Example things you can say:

  • "What skills can you run?"
  • "Use the Auto-Filer skill on this document."
  • "Run Renewals & Warranty Watch."
  • "Format my Garage collection for printing."

#Conversations & History

Your Q&A history — every question you've asked and answer you've received.

Tool What It Does
journal_conversation Save a Q&A exchange to your history for searchable recall
recall_history Search your prior conversations — past Q&A, advice given, topics discussed. Filters by channel (voice/text/mcp), platform, session, or date range
list_conversations Browse your full Q&A history in date order, with paging. Use for "show my recent conversations"; use recall_history to find a specific topic
trash_conversation Move a conversation to trash (soft delete)
trash_conversations Bulk move multiple conversations to trash
restore_conversation Restore a conversation from trash

Example things you can say:

  • "What did we talk about last week?"
  • "Recall the recipe advice you gave me yesterday."
  • "What questions have I asked about insurance?"
  • "Delete all conversations from March."

#Change History & Undo

Review and revert recent changes to your inventory. Every edit is tracked and reversible.

Tool What It Does
recent_item_changes See recent edits to inventory items — shows old and new values for each change
undo_item_change Revert a single-item edit by re-applying the old values
recent_bulk_changes List recent bulk inventory operations — useful after a mass update
undo_bulk_change Revert an entire bulk update in one call — every item the operation touched goes back

Example things you can say:

  • "What did you just change?"
  • "Undo that last edit."
  • "Show me the recent bulk changes."
  • "Revert the bulk update you made to my kitchen items."

How undo works: Every change is logged with before/after values. You can undo individual edits or entire bulk operations. Undo is available from any surface — in-app chat, voice, Claude Desktop, or the web interface.

#Sharing

Share your items, documents, conversations, and folders via email.

Tool What It Does
share_item Share an inventory item via email — composes a message with the item's key details
share_document Share a document via email — includes title, type, and summary
share_conversation Share a Q&A answer via email
share_view Share a folder via email — includes folder name, content counts, and preview
mount_shared_resource Add something shared with you (or with Everyone) into your own library, so it sits inline alongside your own content — like "Add to My Drive". The master stays with its owner, so you always see their latest version
unmount_shared_resource Remove a mounted shared resource from your library (reversible; doesn't delete the owner's content or revoke your access)
list_mounts List the shared resources you've added to your library
list_mounted_contents Resolve the shared resources you've mounted into a folder into their live data + provenance, so they show inline alongside your own content

Example things you can say:

  • "Email the olive oil details to my wife."
  • "Share this recipe with Steve."
  • "Send the warranty document to the repair shop."
  • "Add the shared Skills to my library."

#Trash & Restore

Manage your trash across all content types.

Tool What It Does
list_trash See everything currently in the trash, ordered by most recently trashed
restore_trash Generic restore — works for items, documents, and conversations without needing to know the type
empty_trash Permanently delete trash entries. Optional scope: "item", "document", or "all"

Example things you can say:

  • "What's in my trash?"
  • "Restore the last thing I deleted."
  • "Empty the trash."

#Search & Discovery

Cross-cutting tools for finding information and getting answers.

Tool What It Does
web_search Search the web for current information — used when you need real-time data, recent events, or fact verification
query_expert Ask another AI model for a second opinion mid-conversation. Useful for comparing perspectives
get_user_context Assembles relevant context for your query — bio, nearby beacons, focus item details

Example things you can say:

  • "What's the current price of a KitchenAid mixer?" (triggers web search)
  • "Ask Gemini what it thinks about this recipe." (query expert)
  • "What do you know about me?" (user context)

#Settings & Profile

Read and update your profile and app settings — all manageable via voice or chat.

#Profile

Tool What It Does
get_profile Get your profile — name, nickname, email, photo, timezone, home/work locations, and bio
update_profile Update profile fields — first name, last name, nickname, hail name, home/work location, and bio
upload_profile_image Upload a new profile photo from image data
reimagine_profile_image Re-render your profile photo as a claymation figurine portrait

#Identity & Roles

Tool What It Does
get_identity Who you are and what you can do — your uid, email, role (superuser / brand-admin / brand-user / enduser), and whether you're a superuser
set_user_role (Superuser only) Grant or change a user's role by uid or email — audited; writes both the auth claim and the profile mirror so they stay in sync

#Interests ("How I Roll")

Tool What It Does
list_interests List your interests / "how I roll" tags — free-text preferences that personalize AI responses
add_interest Add an interest tag (e.g. "vegetarian", "loves hiking")
remove_interest Remove an interest by id

#AI & Scanning

Tool What It Does
get_ai_model_pref Get your default AI model preference
update_ai_model_pref Set your default AI model — validated against the model registry
get_ble_scan_rate Get your Bluetooth tag scan rate: off, eco, normal, or turbo
update_ble_scan_rate Set your Bluetooth scan rate

#App Behavior

Tool What It Does
get_app_behavior_prefs Get app-behavior preferences — haptic feedback, sounds, keep source photos
update_app_behavior_prefs Update haptic feedback, feedback sounds, or the "keep source photos" toggle
get_background_trails_pref Get your background location trails master switch state
update_background_trails_pref Toggle background location trails on or off

#Save Destinations

Tool What It Does
get_save_preferences Get your sticky save-destination — the folder new scans/items default into
update_save_preferences Set or clear your default save folder

#Notifications & Context Sharing

Tool What It Does
get_notification_preferences Get beacon-category notification preferences — which categories are disabled
update_notification_preferences Toggle notifications for a single beacon category, or bulk enable/disable all
get_context_sharing Get third-party context-sharing preferences — master switch + per-service toggles
update_context_sharing Toggle context sharing for Claude Desktop, McCormick, Amazon, etc.

#Account Management

Tool What It Does
get_account_deletion_precheck Pre-flight check — shows data counts, subscription status, and warnings
request_account_deletion Request account deletion. Creates a confirmation with 5-minute expiry

Example things you can say:

  • "Switch my default AI to Claude."
  • "Turn off haptic feedback."
  • "Set my scan rate to turbo."
  • "Turn off location trails."
  • "Stop sharing context with Amazon."
  • "Give me a claymation profile picture."

#Privacy

Control how your ambient data (location, beacons) is shared with AI calls.

Tool What It Does
get_privacy_preferences Get your ambient-data privacy preferences — location precision per AI call type
update_privacy_preferences Update location precision settings for different AI call types

Example things you can say:

  • "What are my privacy settings?"
  • "Don't share my exact location with AI — use city-level only."

#Voice Preferences

Control how the assistant speaks to you.

Tool What It Does
get_voice_preferences Get your voice/TTS settings — voice name, style, auto-speak, playback speed
update_voice_preferences Update voice name, style, auto-speak toggle, or playback speed

Example things you can say:

  • "Switch to the Shimmer voice."
  • "Speed up your speech."
  • "Stop auto-speaking responses."
  • "What voice are you using?"

#Settings Catalog

Browse all available settings and their current values.

Tool What It Does
list_user_settings Read every settings document you have in a single structured payload
list_setting_dimensions Read the catalog of settings the AI can manage on your behalf

Example things you can say:

  • "Show me all my settings."
  • "What settings can you change for me?"

#Subscription & Usage

Check your plan, credit balance, and usage history.

Tool What It Does
get_subscription Get your subscription summary — tier, period dates, credits used/remaining, exemption status
get_usage_state Get current usage and billing summary — tier, credits, streak, exemption status
get_billing_events Get itemized billing history — individual AI requests with credits consumed, model used, and token counts

Example things you can say:

  • "How many credits do I have left?"
  • "What plan am I on?"
  • "Show me my usage this month."
  • "What's my most expensive AI request?"

#Export & Import

Move your data in and out of ambientChat.

Tool What It Does
export_user_data Start an export of all your data as a ZIP archive — inventory, documents, conversations, preferences, settings, profile
get_export_status Check if your export is ready and get the download URL
get_import_upload_url Get a secure upload URL for importing data
import_user_data Import data from an uploaded archive — preserves original IDs and reconciles links

Example things you can say:

  • "Export all my data as a ZIP."
  • "Is my export ready?"
  • "Import data from the file I uploaded."

#Onboarding & Help

Get started and find help.

Tool What It Does
get_ambientchat_welcome Get your personalized welcome card — tiles, greeting, suggested prompts, and next best action
get_help Search the help documentation (Don't Panic guides) for answers to your question
get_onboarding_state Read your onboarding progress — tier, engagement metrics, dismissed tiles, activation status
update_onboarding_state Update onboarding preferences — dismiss tiles, restore dismissed items, reset
record_onboarding_event Record onboarding analytics events (used internally for A/B analysis)

Example things you can say:

  • "How do I scan a receipt?"
  • "Show me the getting started guide."
  • "Dismiss the welcome card."

#User Stats

Tool What It Does
get_user_stats Get counts of your content — active and trashed inventory items, documents, folders, and conversations

Example things you can say:

  • "How many items do I have?"
  • "Give me an overview of my account."

#Confirmation Tools

Safety gates for irreversible actions. Some operations create a pending confirmation that you must approve within a short time window.

Tool What It Does
list_pending_confirmations See actions awaiting your approval
confirm_action Approve a pending action
deny_action Reject a pending action

Tools that require confirmation: request_account_deletion Tools that require failsafe confirmation: empty_trash

#Scan Regression Tools (Developer Only)

These tools are restricted to superusers for internal quality testing.

Tool What It Does
get_scan_regression_runs List recent scan-regression harness runs with summary metrics
get_scan_regression_run Fetch one scan-regression run with full per-fixture detail
run_scan_regression Trigger a scan-regression run against deployed code
get_scan_regression_request Check the status of a previously created scan-regression request

#How to Connect

#The MCP Server URL

https://mcp.ambientchat.ai

That's the address. Point any MCP-compatible client at it, sign in with your ambientChat credentials, and the tools above become available.

#Via Claude Desktop (MCP)

  1. Open Claude Desktop settings
  2. Navigate to the MCP Servers configuration
  3. Add a new MCP server with the URL https://mcp.ambientchat.ai
  4. Authenticate with your ambientChat credentials
  5. Claude Desktop will discover all available tools automatically

#Using Tools in Conversation

Once connected, you don't need to call tools by name. Just ask natural questions and the AI uses the appropriate tools:

  • "What food is expiring this week?" → list_expiring_items
  • "Find my Costco receipts from January." → search_documents
  • "How much is my electronics collection worth?" → search_items
  • "Create a packing list for my Hawaii trip." → create_markdown_document
  • "Change all items in the kitchen to category Food." → update_items_by_filter
  • "Undo that last bulk change." → undo_bulk_change
  • "Export all my data as CSV." → export_user_data
  • "What did we talk about last week?" → recall_history
  • "Share this recipe with my wife." → share_conversation

#Tips & Tricks

  • Same context everywhere. MCP gives external clients the same context as in-app chat. The search quality, semantic matching, and data access are identical.
  • Great for desktop workflows. Writing a report? Planning a meal? Doing insurance paperwork? Your full inventory and document archive is accessible without switching to your phone.
  • Combine tools naturally. Search your inventory, then create a document summarizing what you found. The tools compose together — search, analyze, write, save — all in one conversation.
  • Everything is undoable. Bulk changes, individual edits, trash operations — all reversible. Say "undo that" and the AI knows what you mean.
  • Voice works too. Every tool listed here works identically via voice in the mobile app. Just say what you need.

#Known Limitations

  • Requires a compatible MCP client. Claude Desktop is the primary supported client. The MCP server follows the standard protocol.
  • Uploading images/files now works via MCP. Use upload_document with inline base64 (small files) or the get_document_upload_url → PUT → upload_document flow (any size). In claude.ai chat, dropping in a photo and saying "save this to my Medical folder" works when code execution is enabled — the assistant uploads the attached file for you. Live, on-device camera scanning still happens in the mobile app.
  • Rate limits apply. MCP tool calls consume the same credits as in-app chat. Your subscription tier determines available credits.
  • Real-time sync is not instant. If you scan something on your phone, it may take a few seconds before MCP tools see the new item.

#Version History

Version Date What Changed
13 2026-06-26 Added list_mounted_contents — resolve mounted shares into live data + provenance for inline display (AMB-377)
12 2026-06-26 Added mount_shared_resource / unmount_shared_resource / list_mounts — add shared content into your own library (AMB-376)
11 2026-06-25 Added list_skills / get_skill — first-party SKILL.md skills, readable by everyone (AMB-350)
10 2026-06-07 Terminology: undo surfaces say "the web interface" not "admin console"
1 2026-03-01 Initial guide — 28 tools across 6 categories
2 2026-05-27 Complete rewrite — all 93 user-facing tools across 17 categories (AMB-188)
3 2026-05-28 Added the MCP server URL (https://mcp.ambientchat.ai); reverted title to v1 to keep the seed idempotent
4 2026-05-29 Added get_document_upload_url; upload_document now accepts base64 / signed-URL bytes so MCP clients can upload images into folders (AMB-281)
5 2026-05-28 Added list_conversations (browse Q&A history with paging) — AMB-104 MCP promotion
6 2026-05-29 Added get_save_preferences / update_save_preferences (sticky save folder) — AMB-104 MCP promotion
7 2026-05-29 Added list_interests / add_interest / remove_interest (How I Roll tags) — AMB-104 MCP promotion
8 2026-06-01 get_profile / update_profile now read & write bio (folded in from the legacy profile field, which was removed) — AMB-104
9 2026-06-01 Added get_scan_status — query an upload/scan job by jobId (processing / complete / failed) — AMB-287