Your AI. On the home team.
Connect your assistant to Uskeep
Let your AI help with projects, errands, recipes, dinner plans and shopping lists. Connect with your Uskeep account and choose what it can read or change. You don’t need an API key.
A little extra help at home
Connect ChatGPT
Bring your household’s projects, errands and meals into ChatGPT. For now, add Uskeep as a custom MCP plugin using the steps below. A public Uskeep plugin is not available yet.
Select the URL, then use your device’s Copy action.
- In ChatGPT on the web → Plugins, select the plus button, then Add custom MCP server.
- Name it Uskeep. Under Connection, paste
https://uskeep.app/mcpas the Server URL. - Choose OAuth and automatic client registration (DCR). Leave the client ID and client secret empty.
- Review ChatGPT’s risk warning. If you want to proceed, approve it and select Create as a plugin.
- Find Uskeep in your plugins and select Install. When prompted, sign in to Uskeep, check your household and return address, choose what ChatGPT can read or change, then select Allow connection.
- In a ChatGPT conversation, type @ and select Uskeep. Try “What errands are open?” with Errands read access.
Custom MCP plugins depend on your ChatGPT workspace permissions and security settings. If the option is missing, check with your workspace owner. OpenAI’s setup guide.
You choose the permissions. Disconnect anytime in Uskeep Settings → AI Agents. Connections expire after 30 days; reconnect to renew access.
Claude and Claude Desktop
- Open your client’s Connectors settings and add a custom remote MCP connector.
- Name it Uskeep and enter
https://uskeep.app/mcpas the server URL. - Choose OAuth / sign in. If asked how to identify the OAuth client, choose Register automatically (dynamic client registration). You do not need to enter a client ID, client secret or API key.
- Connect, sign in to Uskeep, check your household and the app’s return address, choose permissions, then select Allow connection.
- Enable the connector in your conversation. Try “What errands are open?” if you granted Errands read access.
Connector menus and availability depend on your client and workspace settings. Team or Enterprise owners may need to add the connector first. Claude’s connector guide.
Claude Code
Add the server without a bearer header:
claude mcp add --transport http uskeep https://uskeep.app/mcpOpen /mcp in Claude Code, select Uskeep and authenticate. Finish Uskeep sign-in and approve access in your browser. Add --scope user to the command if you want the connection available across projects. Claude Code’s MCP guide.
Other MCP clients and agent installers
- Add a remote HTTP / Streamable HTTP MCP server with URL
https://uskeep.app/mcp. - Enable OAuth. Let the client discover the authorization server and register automatically.
- Hand sign-in and consent to the user in their browser. Never ask them to paste a Google token, browser cookie or password into a chat.
- After approval, initialize MCP, call
tools/listand use tools permitted by the approved scopes.
Agents can read the plain Markdown guide or start from /llms.txt. This guide is public and requires no household access. Clients that use plain HTTP instead of MCP can use the REST API at https://uskeep.app/v1 with the same account sign-in; see the REST API guide.
Protocol details for client developers
- Protected resource metadata:
/.well-known/oauth-protected-resource/mcp(also available at the root well-known path). - Authorization server metadata:
/.well-known/oauth-authorization-server. - OAuth authorization-code flow with S256 PKCE; dynamic registration at
/oauth/register. Token and refresh requests use form encoding at/oauth/token. - Include
resource=https://uskeep.app/mcpin authorization and token requests. Redirect URIs must match registration exactly and use HTTPS or native-client loopback HTTP. - Short-lived access tokens last up to one hour. Refresh tokens rotate and remain bounded by the 30-day connection. Reusing a spent refresh token disconnects that connection.
- MCP uses stateless POST requests returning JSON. GET and DELETE return 405. A POST without valid credentials returns 401 with a discovery challenge in
WWW-Authenticate.
Choose what your assistant can do
For each area, choose no access, read only, or read and change. Meals includes recipes, meal plans and shopping. Write permission also requires reading the same area.
| Area | OAuth scopes |
|---|---|
| Projects and tasks | projects:read, projects:write |
| Errands | errands:read, errands:write |
| Recipes, dinners and shopping | meals:read, meals:write |
If a client omits scopes, Uskeep requests read and change access to all three areas. Consent selects Read and change wherever the client requests write access; choose Read only or No access to narrow it before approving. Explicitly requested narrower scopes are respected; read-only requests stay read-only. Existing connections retain their permissions, including when refreshed. Overview and Activity combine all areas and require all three read scopes; use an individual area’s tools for a restricted connection.
A connection acts as the signed-in person in their current household. Changes appear in Activity with the app’s name. Household administration, invitations, browser sessions and key management are unavailable to MCP agents.
Disconnect or change permissions
Open Settings → AI Agents, expand the connection and select Disconnect agent. All its access and refresh tokens stop working immediately. Reconnect to change permissions or after the connection expires in 30 days. Moving households also revokes the old connection.
Optional API keys
For scripts and clients that need a fixed bearer header, use Settings → AI Agents → Create an agent key. Choose permissions and an expiry, confirm your account if prompted, and copy the secret once. Keep it in your client’s secret storage.
New manual keys default to read and change access across Projects, Errands and Meals. Reduce permissions before creating the key if needed. POST /api/me/keys uses the same default when scopes is omitted. Existing keys keep their permissions; create a replacement to change access.
Use the same MCP URL with Authorization: Bearer <your-agent-key>. The same key also works with the REST API at https://uskeep.app/v1. The REST API also accepts account sign-in: an OAuth connection made with resource=https://uskeep.app/v1. OAuth tokens work only for the resource they were issued for, so an MCP token does not work at /v1. See the REST API guide.
Use list_attachments to find shared images and PDFs by filename or linked item. Give 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.
Troubleshooting
- 401 / sign-in required: use your client’s authenticate or reconnect action. A browser cookie alone does not authenticate MCP.
- 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 Uskeep sign-in, then choose permissions and allow access. Expired consent must be restarted.
- Forbidden tool: reconnect and approve the required area. If only some areas are allowed, use their list/get tools instead of Overview or Activity.
- Invalid resource, callback or PKCE: start a fresh connection with automatic registration, the exact server URL above, and S256 PKCE.
- Client only supports fixed tokens: use an optional API key.
Need a hand?
For Uskeep connection help, email cvolzer3@gmail.com. Describe the step that failed; never send passwords, API keys or connection tokens.