# Uskeep

> A shared household workspace for people and their AI agents: projects, errands,
> recipes, weekly dinners, shopping lists and Activity.

## If a person gave you this link

The person wants you to connect to their Uskeep household. They are probably not
technical: do the setup yourself, and ask them for one thing only, to approve the
connection on a Uskeep page. Follow these steps:

1. Pick the way you can connect.
   - Preferred: if your client can add a remote MCP server, add
     `https://uskeep.app/mcp` (Streamable HTTP) with OAuth and automatic client
     registration. Your client then gives you the Uskeep sign-in page.
   - Otherwise, use the REST API at `https://uskeep.app/v1`. Register a client with
     `POST https://uskeep.app/oauth/register`, start the authorization-code flow with
     S256 PKCE at `https://uskeep.app/oauth/authorize` with
     `resource=https://uskeep.app/v1`, and exchange the code at
     `https://uskeep.app/oauth/token` (form-encoded, same `resource`). Details and a
     worked example: https://uskeep.app/docs/api.md (Authentication, Option 1).
   - If you can do neither (for example, a chat without tools), tell the person to
     follow the step-by-step guide for their assistant at https://uskeep.app/docs/mcp
     (ChatGPT: https://uskeep.app/docs/mcp#chatgpt).
2. Open (or show) the Uskeep authorization URL for the person and tell them in plain
   words: "Sign in to Uskeep, choose what I may see or change, then press
   Allow connection."
3. Never ask the person for passwords, Google or Apple tokens, browser cookies, or to
   create API keys. Only if OAuth is impossible for you, explain that they can create
   a key in Settings → AI Agents (https://uskeep.app/settings/agents, under "For
   developers and advanced setup") and paste it to you.
4. Confirm success: call `GET https://uskeep.app/v1/me` (REST) or the MCP tool
   `get_overview` (it needs read access to all three areas; with less access, use a
   permitted list tool such as `list_errands`). Tell the person what you can now see,
   for example their household name and open errands.
5. Permissions: if a call returns 403 (or a forbidden MCP tool result), ask the person
   to reconnect and allow more access. Do not work around it.

The full instructions are https://uskeep.app/docs/mcp.md (MCP) and
https://uskeep.app/docs/api.md (REST). Sending `Accept: text/markdown` to
https://uskeep.app/docs/mcp or https://uskeep.app/docs/api also returns the Markdown.

## Connect an agent

- [MCP installation guide](https://uskeep.app/docs/mcp.md): Public instructions for
  installing Uskeep in Claude, Claude Code and other MCP clients. Use OAuth and the
  user's Uskeep sign-in; an API key is optional.
- [Human setup guide](https://uskeep.app/docs/mcp): Browser-readable installation,
  permissions, disconnect instructions and troubleshooting.
- [MCP protected resource metadata](https://uskeep.app/.well-known/oauth-protected-resource/mcp)
- [OAuth authorization server metadata](https://uskeep.app/.well-known/oauth-authorization-server)

Server: https://uskeep.app/mcp (Streamable HTTP). Let the user complete browser
sign-in and consent. Discover tool contracts through tools/list after connecting.

## REST API

- [REST API guide](https://uskeep.app/docs/api.md): Authentication (OAuth account
  sign-in with resource https://uskeep.app/v1, or an API key), permissions,
  conventions, every endpoint and curl examples. HTML version: https://uskeep.app/docs/api
- [OpenAPI 3.1 description](https://uskeep.app/docs/openapi.json): Every `/v1`
  operation with its scopes and schemas.
- [API index](https://uskeep.app/v1): Public `GET /v1` discovery document.
- [API catalog](https://uskeep.app/.well-known/api-catalog): RFC 9727 linkset.
- [REST API protected resource metadata](https://uskeep.app/.well-known/oauth-protected-resource/v1)
- [Settings → AI Agents](https://uskeep.app/settings/agents): Where the user creates
  API keys and disconnects agents.

Base URL: https://uskeep.app/v1. Send `Authorization: Bearer <token or key>`. Never ask
the user for a Google token, browser cookie or password.

## Browser agents

- An agent that operates inside the user's signed-in browser on https://uskeep.app can
  call the same routes under `/api` (for example `/api/errands`) with the session
  (`credentials: "same-origin"`, JSON bodies); no key is needed and changes count as the
  person's own. Do not copy cookies out of the browser. Details:
  https://uskeep.app/docs/api.md

## Blog

Short posts from the Uskeep team when something ships, and now and then how we use it.
Every page works without JavaScript.

- [Blog index in Markdown](https://uskeep.app/blog/index.md): every post, newest first,
  with links to each post's Markdown. HTML version: https://uskeep.app/blog
- Each post has a Markdown twin: add `.md` to its URL (for example
  https://uskeep.app/blog/hello.md), or send `Accept: text/markdown` to the post URL.
- Feeds: [RSS](https://uskeep.app/blog/feed.xml), [Atom](https://uskeep.app/blog/atom.xml)
  and [JSON Feed](https://uskeep.app/blog/feed.json), with the full text of each post.
- If a person asks you to keep an eye on the blog, check the RSS feed for new items.

## All documentation

- [Documentation index](https://uskeep.app/docs)