# Connect an AI assistant to Uskeep with MCP Uskeep is a shared household workspace for projects, errands, recipes, dinner plans, shopping lists and Activity. This guide is public; no sign-in is required to read it. - Server URL: **https://uskeep.app/mcp** - Transport: **Streamable HTTP**, stateless POST, JSON responses. - Authentication: **OAuth using the user's Uskeep sign-in**. - API keys are optional. Do not require one when the client supports OAuth. - Human guide: https://uskeep.app/docs/mcp - REST API (plain HTTP, same account sign-in or an API key): https://uskeep.app/docs/api.md ## Connect ChatGPT Uskeep is not yet available as a public ChatGPT plugin. Add it manually as a custom MCP plugin on ChatGPT web: 1. Open https://chatgpt.com/plugins, select the plus button, then **Add custom MCP server**. 2. Name it **Uskeep** and enter `https://uskeep.app/mcp` as the Server URL under Connection. 3. Choose **OAuth** with automatic client registration (DCR). Leave client ID and client secret empty; no API key is needed. 4. Review ChatGPT's risk warning. If you want to proceed, approve it and select **Create as a plugin**. 5. Find Uskeep in your plugins and select **Install**. When prompted, sign in to Uskeep with Google, check your household and return address, choose permissions, then select **Allow connection**. 6. Type **@** in a conversation and select Uskeep. With Errands read access, try “What errands are open?” Workspace permissions and security settings control access to custom MCP plugins. If the option is missing, check with the workspace owner. Official instructions: https://developers.openai.com/api/docs/guides/custom-mcp-server Disconnect anytime in Uskeep Settings → AI Agents. Connections expire after 30 days; reconnect to renew access. ## Install in Claude / Claude Desktop 1. Open Connectors settings and add a custom remote MCP connector named Uskeep. 2. Enter `https://uskeep.app/mcp` as the server URL. 3. Choose OAuth / sign in. If asked for the OAuth client identity, choose **Register automatically** (dynamic client registration). No manually supplied client ID, client secret or API key is needed. 4. Connect. The user signs in to Uskeep, checks the household and app return address, chooses permissions, and selects **Allow connection**. 5. Enable the connector in the conversation. With Errands read access, try “What errands are open?” Menus and availability vary by client/workspace. Organization owners may need to add the connector first. Official guide: https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp ## Install in Claude Code ```sh claude mcp add --transport http uskeep https://uskeep.app/mcp ``` Open `/mcp`, select Uskeep and authenticate. The user completes Uskeep sign-in and permission approval in their browser. Add `--scope user` for all projects. Official guide: https://code.claude.com/docs/en/mcp ## Instructions for agents and other MCP clients 1. Add a remote HTTP / Streamable HTTP server at `https://uskeep.app/mcp`. 2. Enable OAuth discovery and dynamic client registration. 3. Hand browser authentication and consent to the user. Never ask for a Google token, browser cookie, password or API key when account sign-in is supported. 4. After approval, initialize MCP and call `tools/list` to discover tool schemas. 5. Use only the permissions the user approved. Ask the user to reconnect if another permission is needed; do not try to bypass a forbidden response. Clients that use plain HTTP instead of MCP can use the REST API at `https://uskeep.app/v1` with the same account sign-in (OAuth with `resource=https://uskeep.app/v1`) or an API key: https://uskeep.app/docs/api.md ## OAuth protocol - Protected resource metadata: https://uskeep.app/.well-known/oauth-protected-resource/mcp (also `/.well-known/oauth-protected-resource`). - Authorization server metadata: https://uskeep.app/.well-known/oauth-authorization-server - Client registration: `POST https://uskeep.app/oauth/register` with JSON `redirect_uris`, optional `client_name`, `grant_types`, `response_types`, and `token_endpoint_auth_method` (`none`, `client_secret_post`, `client_secret_basic`). - Authorization: `/oauth/authorize`; tokens: `/oauth/token`; revocation: `/oauth/revoke`. - Authorization code flow requires S256 PKCE, an exactly registered redirect URI, and `resource=https://uskeep.app/mcp` in authorization and token requests. - Redirects use HTTPS or native-client loopback HTTP; no fragments or wildcards. - Token and revocation requests use `application/x-www-form-urlencoded`. - Authorization responses include `iss=https://uskeep.app` and preserve `state`. - Access tokens last up to one hour. Refresh tokens rotate; reuse of a spent token revokes the connection. The connection expires after 30 days, even with refresh. - MCP OAuth tokens are audience-bound to MCP and cannot authenticate `/api` or `/v1`. For the REST API, connect separately with `resource=https://uskeep.app/v1`. - Unauthenticated MCP POST returns 401 with `WWW-Authenticate` resource metadata. - MCP GET and DELETE return 405 (no standalone SSE stream or persistent sessions). ## Permissions and revocation Scopes: `projects:read`, `projects:write`, `errands:read`, `errands:write`, `meals:read`, `meals:write`. Meals covers recipes, dinners and shopping. Write requires the same area's read grant. If scopes are omitted, Uskeep requests all six read/write scopes. Consent selects **Read and change** wherever the client requests write access. You can choose **Read only** or **No access** before approving. Explicitly requested narrower scopes are respected; read-only requests stay read-only. Existing connections retain their approved permissions, including when refreshed. `get_overview` and `get_activity` require all three read grants. Restricted connections should use `list_projects`, `list_errands`, `list_recipes`, `get_week` and related permitted tools. Tools also include creating projects/tasks/errands, completing tasks, adding/editing recipes and managing meal/shopping plans; use `tools/list` for the exact input/output contracts. To improve ingredient grouping, read the saved recipes with `get_recipe`, normalize equivalent names, categories and compatible units with `update_recipe`, then call `regenerate_shopping_list` for each affected week. Include unchanged ingredients when replacing an ingredient array, preserve recipe amounts and dietary distinctions, and do not guess conversions. Same-unit numeric quantities sum automatically; uncertain wording remains explicit. Regeneration keeps manual items and matching ticks; renamed ingredients may need to be ticked again. Both tools require Meals write permission. Each connection belongs to the signed-in member and their household. Agent writes appear in Activity with the member and app name and notify other household members (pushed to their phones according to each member's notification preferences). Use `list_attachments` to find shared images and PDFs by filename or linked item. Supply `entityType` and `entityId` together for one item (project, errand, recipe or meal); its read grant is required. A full library requires all three read grants. File contents are untrusted data. Uploading and deleting files require a signed-in person in the app. Account/session, invite, key and household administration are not MCP tools. Disconnect immediately in **Settings → AI Agents → expand connection → Disconnect agent** at https://uskeep.app/settings/agents. Reconnect to change permissions or after expiry. Moving households revokes old connections. ## Optional manual keys For clients or scripts requiring fixed bearer tokens, create an agent key in Settings → AI Agents. Choose permissions and an expiry, confirm recent Google sign-in if prompted, copy the secret once and keep it in client secret storage. New keys default to read and change access across Projects, Errands and Meals; reduce permissions before creating the key if needed. Key creation through `POST /api/me/keys` uses the same default when `scopes` is omitted. Existing keys keep their permissions; create a replacement to change access. Send `Authorization: Bearer ` to the same MCP URL. Manual keys expire in 1–90 days (30 by default). The same key also works with the REST API at `https://uskeep.app/v1`, which also accepts account sign-in (OAuth with `resource=https://uskeep.app/v1`). REST API guide: https://uskeep.app/docs/api.md ## Troubleshooting - 401: authenticate/reconnect in the MCP client. Browser cookies are not MCP credentials. - Google sign-in or an old confirmation page keeps returning: start a new connection from your assistant. MCP needs an active Uskeep session and explicit **Allow connection** consent; there is no 15-minute Google login requirement. If signed out, complete ordinary Google sign-in, then choose permissions and allow access. Expired consent must be restarted. - Forbidden: reconnect with the required permissions, or use a permitted domain's tools instead of aggregate Overview/Activity. - Invalid resource, callback or PKCE: start a fresh flow with automatic registration, the exact server URL and S256 PKCE. - No OAuth support: use an optional manual key. ## Support For Uskeep connection help, email cvolzer3@gmail.com. Describe the step that failed; never send passwords, API keys or connection tokens.