Using Orbrey with Claude (MCP)

Orbrey ships an MCP (Model Context Protocol) server so Claude — and any other MCP-aware client — can act on your household data directly. Ask Claude to plan a week of dinners, mark tasks done, or sync the meal plan to your grocery list, and it does so by calling Orbrey's API through a secure OAuth-protected endpoint.

Setup URL

Add this URL as a custom MCP connector in your client of choice:

https://mcp.orbrey.com/

The server is OAuth 2.1 with PKCE and Dynamic Client Registration. The first call from a new client opens the Orbrey consent page in your browser — pick which household(s) to authorise and which scopes to grant, then Allow. The connector is good from that point on; revoke access any time from Settings → Integrations.

Connecting Claude

Claude Desktop / Claude.ai web

Open Settings → Connectors → Add custom connector, paste https://mcp.orbrey.com/, click Add, and complete the browser-based consent flow.

Claude Code

Pre-registered loopback ports: 8080, 33418, 3334.

claude mcp add --transport http --callback-port 8080 \
  orbrey https://mcp.orbrey.com/

ChatGPT

ChatGPT supports MCP Apps using the same protocol. Add https://mcp.orbrey.com/ as a custom MCP server; the Orbrey widgets render in chat the same way they do in Claude.

What you can do

The server exposes 30 tools across nine Orbrey domains. Each tool is scoped (read-only or write) and you choose which scopes to grant per household at consent time.

Free-tier scopes

• Tasks — list occurrences, mark complete / skipped, delete an occurrence.
• Calendar — list events, create events, sync to / from Google / Outlook (idempotent).
• Recipes — list, create, archive.
• Grocery — list items, add items, merge duplicates.
• Shared lists — list, create, add items, delete.
• Rewards (gems) — view member balances, credit or debit a wallet.
• Households — list authorised households, set the default.
• Today snapshot — composite read of today's tasks + events for morning briefings.

Plus-tier scopes

• Pantry — list (with optional location and expiring-within-N-days filters), add, consume, soft-delete.
• Meal planning — read a week, set a slot to a recipe, clear a slot, sync the week's recipes into the grocery list.

Inline widgets

Ten of the tools return interactive UI in chat (built on the MCP Apps SDK). Examples:

• “What's on today?” → Today Agenda card with one-tap task completion.
• “Show this week's meal plan” → 7-day grid with a Sync-to-grocery button.
• “What's in my pantry?” → shelf view grouped by location with expiry alerts.
• “Show member balances” → wallet chips with inline gem-adjust.

Which Claude clients render the widgets?

MCP Apps support is rolling out unevenly. The Orbrey server is spec-compliant — when a client adds widget support, our widgets render automatically with no changes on our end.

Hosts that don't render widgets get a human-readable markdown summary instead of a raw JSON dump — e.g. asking “list my recipes” in Claude Code returns a tidy bullet list, just without the swipeable cards you'd see in Claude Desktop.

Hosts that don't support MCP Apps yet still get the raw text result, so the integration degrades gracefully.

Safety, auth and data

• OAuth 2.1 with PKCE, Dynamic Client Registration (RFC 7591), Resource Indicators (RFC 8707), and RFC 9728 protected- resource metadata.
• Per-household, per-scope grants — every tool call checks the bearer token's household grant and required scopes.
• Row Level Security — Orbrey's database enforces household isolation at the database level; the MCP server cannot leak data across households even if a bug tried.
• Rate-limited at the Cloudflare edge (60 calls / min per token).
• Audit log — every invocation writes a structured event with the household id, user id, OAuth client id, tool name, latency, and outcome.
• Plus-tier gating — pantry and meal-planner tools check the household's subscription before executing.
• No conversation data leaves your client. The server only sees the structured tool arguments Claude sends; it never reads chat history.

Troubleshooting

“No household is authorised for this MCP client”

Remove the connector in your MCP client and re-add it. The consent flow records which household(s) you authorised; if no household is selected, the server has nothing to act on.

“Tool requires an Orbrey Plus subscription”

The pantry and meal-planner tools are Plus features. Upgrade from Settings → Billing, then retry. The free-tier tools work on any plan.

“Rate limit exceeded”

60 calls / minute per token. Wait a minute and retry — the limit resets continuously.

The widget shows “Connecting…” forever

Your client may not have MCP Apps enabled. Update Claude Desktop or switch to Claude.ai web; the tool will still work in text-only mode.

Disconnecting

Remove the connector in your MCP client AND revoke the OAuth grant from Settings → Integrations in the Orbrey app. The grant is what authorises the bearer token; revoking it stops all further tool calls from that client immediately.