#MCP Tools — Using ambientChat with Claude Desktop
Your AI context doesn't have to stay trapped inside one app. With MCP, you can bring your entire ambientChat world into Claude Desktop — and it works exactly like having a very well-informed research assistant sitting at your desk.
#What It Does
MCP stands for Model Context Protocol. It's a standardized way for AI tools to access external data sources — in this case, your ambientChat data. When you connect Claude Desktop to ambientChat via MCP, Claude gains the ability to search your inventory, read your documents, recall your conversation history, and even create new documents — all without you ever opening the mobile app.
Think of it as giving Claude Desktop a direct line to everything you've cataloged, scanned, and tracked. It knows what's in your pantry, what receipts you've saved, and what questions you've asked before. The same context that powers your in-app chat experience is now available on your desktop.
All tools respect your authentication. Claude Desktop can only access your data, using your credentials. Nobody else's stuff, ever.
#Available Tools
The MCP server exposes tools organized into seven categories. Here's what's at your disposal:
#Inventory Tools
These let you browse, search, edit, and manage your physical items.
| Tool | What It Does |
|---|---|
list_inventory |
List all items, optionally filtered by category |
get_inventory_item |
Get full details of a specific item (name, brand, price, expiry, location, notes, nutritional data) |
search_inventory |
Semantic search — finds items by meaning, not just keywords ("things in my garage", "snacks for the party") |
get_expiring_items |
Find items expiring within a number of days (default: 14) |
update_inventory_item |
Edit any item field — name, brand, category, price, expiry, location, notes |
trash_inventory_item |
Move an item to trash (requires confirmation) |
restore_inventory_item |
Restore an item from trash |
list_trash |
See what's in the trash |
empty_trash |
Permanently delete everything in trash (requires failsafe confirmation) |
regenerate_item_image |
Generate a fresh AI image for an item |
#Document Tools
Navigate folders, search documents, and manage your digital paperwork.
| Tool | What It Does |
|---|---|
list_folders |
List folders at a given level |
get_folder |
Get folder details and contents |
get_folder_tree |
See the entire folder hierarchy at a glance |
list_documents |
List documents in a folder with optional search |
get_document |
Get document details, AI summary, and linked items |
search_documents |
Keyword search across documents |
search_documents_semantic |
Semantic search — finds documents by meaning |
create_folder |
Create a new folder |
move_document |
Move a document between folders |
update_folder |
Rename or update folder properties |
upload_document |
Upload a new document |
delete_documents |
Delete documents (requires confirmation) |
#Markdown Document Tools
Create, edit, and search your own written documents — notes, lists, reports.
| Tool | What It Does |
|---|---|
create_markdown_document |
Create a new markdown document with optional YAML frontmatter |
update_markdown_document |
Update a document — replace content, or target a specific section by heading |
get_markdown_document |
Retrieve a markdown document's full content and metadata |
list_markdown_documents |
List markdown documents, optionally filtered by folder or tags |
search_markdown_content |
Semantic search across markdown document content |
#Conversation Tools
Access and contribute to your Q&A history.
| Tool | What It Does |
|---|---|
journal_conversation |
Save a Q&A exchange to your history (builds searchable recall) |
Additional conversation functions (list, search, get, delete) are available through the internal API and may be exposed to MCP clients in future updates.
#Export & Import Tools
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 (JSON or CSV format) |
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 |
#Confirmation Tools
Safety gates for irreversible actions.
| Tool | What It Does |
|---|---|
list_pending_confirmations |
See actions awaiting your approval |
confirm_action |
Approve a pending action |
deny_action |
Reject a pending action |
#How to Use It
#Via Claude Desktop (MCP)
Setting up the connection:
- Open Claude Desktop settings
- Navigate to the MCP Servers configuration
- Add a new MCP server with your ambientChat MCP server URL (provided by your organization or found in your account settings)
- Authenticate with your ambientChat credentials
- 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 Claude Desktop natural questions and it will use the appropriate tools:
- "What food is expiring this week?" — uses
get_expiring_items - "Find my Costco receipts from January." — uses
search_documents - "How much is my electronics collection worth?" — uses
search_inventory - "Create a packing list for my Hawaii trip." — uses
create_markdown_document - "Update the price of my standing desk to $450." — uses
update_inventory_item - "Export all my data as CSV." — uses
export_user_data
Confirmation flow for dangerous actions:
Some tools require confirmation before they execute. When you ask Claude Desktop to delete items or empty trash:
- The tool creates a pending confirmation with a short expiry window
- You review the summary and confirm (or deny) within that window
- Only confirmed actions execute — nothing destructive happens silently
Tools requiring confirmation: trash_inventory_item, delete_documents
Tools requiring failsafe confirmation: empty_trash
#Tips & Tricks
- MCP gives Claude Desktop the same context as in-app chat. The search quality, semantic matching, and data access are identical. If the in-app assistant can find something, Claude Desktop can too.
- Great for desktop workflows. Writing a report? Planning a meal? Doing insurance paperwork? Having your full inventory and document archive accessible from Claude Desktop means you can work with your data without switching to your phone.
- Combine tools naturally. Ask Claude to search your inventory, then create a document summarizing what it found. The tools compose together — search, analyze, write, save — all in one conversation.
#Options
| Setting | What It Does | Default |
|---|---|---|
| MCP Server URL | The endpoint Claude Desktop connects to | Set during configuration |
| Authentication | Your ambientChat login credentials | Required |
| Confirmation timeout | How long you have to confirm destructive actions | 5 minutes |
#Known Limitations
- Requires Claude Desktop or a compatible MCP client. The MCP server follows the standard protocol, but you need a client that supports it. Claude Desktop is the primary supported client.
- Some tools are external-workflow only.
get_import_upload_urlandimport_user_datarequire a client-side file upload step that not all MCP clients handle natively. - Image scanning is not available via MCP. You can't snap a photo through Claude Desktop — use the mobile app for scanning, then access the results via MCP.
- Rate limits apply. MCP tool calls consume the same credits as in-app chat. Your subscription tier determines your available credits.
- Real-time sync is not instant. If you scan something on your phone, it may take a few seconds before MCP tools can see the new item.
#Version History
| Version | Date | What Changed |
|---|---|---|
| 1 | 2026-03-01 | Initial guide |