#MCP Integration — Connecting AI Agents to Your Context
Your AI context doesn't have to stay trapped inside one app. With MCP, any AI agent — Claude Desktop, OpenClaw, or any compatible client — can tap into everything you've cataloged, scanned, and tracked in ambientChat.
#Why This Matters
AI agents are increasingly autonomous — they browse the web, write code, manage your calendar, and control smart devices. But they're blind to your physical world. They don't know what's in your pantry, where you left your tools, or when your prescriptions expire.
ambientChat is context as a service for the physical world. When you connect an agentic framework like OpenClaw to ambientChat, your agent gains awareness of your physical environment:
- A cooking agent that knows exactly what ingredients you have and what's about to expire
- A shopping agent that checks your inventory before adding items to the cart
- A home management agent that knows which rooms have which items and when things need attention
- An insurance agent that can list everything you own and what it's worth
Without this context, agents guess. With it, they act on reality.
#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 any MCP client to ambientChat, that client gains the ability to search your inventory, read your documents, recall your conversation history, and even create new documents.
The same context that powers your in-app chat experience becomes available to any connected agent. All tools respect your authentication — agents can only access your data, using your credentials.
#How to Connect
#OpenClaw (Telegram, Discord, and more)
OpenClaw is an agentic framework that lets you interact with AI through messaging platforms like Telegram. Connecting it to ambientChat gives your Telegram bot full awareness of your physical world.
Prerequisites:
- A Mac, Linux box, or server running OpenClaw
- Node.js installed (
npxavailable in your terminal) - An ambientChat account with a password set
Setup (one command):
On the machine running OpenClaw, run:
openclaw mcp set ambientchat '{"command":"npx","args":["-y","mcp-remote","https://mcp.ambientchat.ai/mcp"]}'
First-time authentication:
- After running the command, trigger any ambientChat tool through your OpenClaw interface (e.g., ask "what's in my inventory?" via Telegram)
- A browser window opens on the OpenClaw host machine showing the ambientChat login page
- Sign in with Google, Apple, or email/password
- You'll see a "Connected!" confirmation — you can close that browser tab
- Tokens are cached locally, so you won't need to sign in again for 30 days
That's it. Your OpenClaw agent can now search your inventory, check expiry dates, read your documents, and more — all through natural conversation in Telegram.
Troubleshooting:
| Problem | Fix |
|---|---|
| "Safari Can't Connect to localhost" | The auth relay process died. Run rm -rf ~/.mcp-auth/ and try again. If it persists, retry quickly — the process has a short timeout window. |
| Browser doesn't open | Check that a default browser is configured on the OpenClaw host. You can also manually open the URL printed in the terminal. |
| "Unknown client_id" error | Clear cached state: rm -rf ~/.mcp-auth/ and retry. |
| Tools stop working after ~30 days | Token expired. Trigger any tool to restart the auth flow. |
#Claude Desktop
- Open Claude Desktop → Settings → MCP Servers
- Add a new server with URL:
https://mcp.ambientchat.ai/mcp - Authenticate with your ambientChat credentials when prompted
- Claude Desktop discovers all available tools automatically
#Claude Code and Other MCP Clients
Any MCP-compatible client can connect using the server URL:
https://mcp.ambientchat.ai/mcp
The server supports OAuth 2.1 with PKCE for authentication and the Streamable HTTP transport. Clients that support mcp-remote can use the same setup pattern as OpenClaw.
#Available Tools
The MCP server exposes tools organized into seven categories:
#Inventory Tools
| Tool | What It Does |
|---|---|
list_inventory |
List all items, optionally filtered by category |
get_inventory_item |
Get full details of a specific item |
search_inventory |
Semantic search — finds items by meaning ("things in my garage") |
get_expiring_items |
Find items expiring within N days (default: 14) |
update_inventory_item |
Edit any item field — name, brand, 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 confirmation) |
regenerate_item_image |
Generate a fresh AI image for an item |
#Document Tools
| Tool | What It Does |
|---|---|
list_folders |
List folders at a given level |
get_folder / get_folder_tree |
Get folder details or full hierarchy |
list_documents |
List documents in a folder |
get_document |
Get document details, AI summary, and linked items |
search_documents / search_documents_semantic |
Keyword or semantic search across documents |
create_folder |
Create a new folder |
move_document |
Move a document between folders |
upload_document |
Upload a new document |
#Markdown Document Tools
| Tool | What It Does |
|---|---|
create_markdown_document |
Create a new markdown document with optional YAML frontmatter |
update_markdown_document |
Update a document — full or section-level |
get_markdown_document |
Retrieve full content and metadata |
list_markdown_documents |
List documents, filtered by folder or tags |
search_markdown_content |
Semantic search across markdown content |
#Conversation & History Tools
| Tool | What It Does |
|---|---|
journal_conversation |
Save a Q&A exchange to your searchable history |
recall_history |
Search your past conversations |
#Export & Import Tools
| Tool | What It Does |
|---|---|
export_user_data |
Export all your data as a ZIP archive |
get_export_status |
Check export progress and get download URL |
import_user_data |
Import data from an uploaded archive |
#Profile & Preferences
| Tool | What It Does |
|---|---|
get_profile / update_profile |
View or edit your profile |
get_voice_preferences / update_voice_preferences |
Manage AI voice settings |
get_notification_preferences |
View notification settings |
#Confirmation Tools
| Tool | What It Does |
|---|---|
list_pending_confirmations |
See actions awaiting approval |
confirm_action / deny_action |
Approve or reject a pending action |
#Tips & Tricks
- Same context everywhere. The search quality, semantic matching, and data access are identical whether you're using the mobile app, Claude Desktop, or OpenClaw.
- Great for desktop workflows. Writing a report? Planning a meal? Having your full inventory accessible from your desktop means you don't need to switch to your phone.
- Combine tools naturally. Ask the agent to search your inventory, then create a document summarizing what it found. Search, analyze, write, save — all in one conversation.
- Context flows to the best model. OpenClaw lets you choose which LLM processes your request. Your ambientChat context follows — it's not locked to any single AI provider.
#Options
| Setting | What It Does | Default |
|---|---|---|
| MCP Server URL | The endpoint your client connects to | https://mcp.ambientchat.ai/mcp |
| Authentication | Your ambientChat login credentials | Required |
| Confirmation timeout | Time to confirm destructive actions | 5 minutes |
#Known Limitations
- Browser required for first auth. The OpenClaw host machine needs a browser to complete the initial OAuth flow. Headless servers need
mcp-remote's--headerflag with a pre-obtained token. - Image scanning is not available via MCP. Use the mobile app for scanning, then access results via MCP.
- Rate limits apply. MCP tool calls consume the same credits as in-app chat.
- 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.
- Token refresh is automatic but requires a browser if the refresh token expires (after ~30 days).
#Version History
| Version | Date | What Changed |
|---|---|---|
| 2 | 2026-04-12 | Broadened to cover all MCP clients. Added OpenClaw setup guide, "context as a service" framing, troubleshooting table, profile/preference tools. |
| 1 | 2026-03-01 | Initial guide (Claude Desktop only) |