# Simple House Planner auth.md

This file tells AI agents and MCP clients how to get access to a person's plans on Simple House Planner. There are no API keys and no accounts for agents themselves. An agent always acts for one person, who signs in and agrees.

`search_furniture` on the MCP server, the public API at https://simplehouseplanner.com/openapi.json and the WebMCP tools in the browser need no sign-in.

## Discover

- Resource: `https://simplehouseplanner.com/mcp` (Streamable HTTP)
- Resource metadata (RFC 9728): `https://simplehouseplanner.com/.well-known/oauth-protected-resource/mcp`
- Authorization server: `https://simplehouseplanner.com/api/auth`
- Authorization server metadata (RFC 8414): `https://simplehouseplanner.com/.well-known/oauth-authorization-server/api/auth`

## Pick a method

Use one of these two methods. Neither needs a person to set anything up first.

1. **Client ID metadata document.** Your `client_id` is the HTTPS address of your client metadata document. Use this if you can host one.
2. **Dynamic client registration (RFC 7591).** Use this if you cannot.

## Register

With a client ID metadata document, there is nothing to send. The server fetches the document when you ask for authorization.

With dynamic registration, `POST https://simplehouseplanner.com/api/auth/oauth2/register` with your client metadata. The limit is 5 registrations a minute.

## Claim

Send the person to `https://simplehouseplanner.com/api/auth/oauth2/authorize`, with the authorization code flow and PKCE (`S256`). Set `resource=https://simplehouseplanner.com/mcp`. The person signs in with Google, an email link or a passkey, and then approves your client and its scopes.

| Scope            | Gives access to                                |
| ---------------- | ---------------------------------------------- |
| `projects:read`  | List, read and describe the person's plans.    |
| `projects:write` | Create, change, rename and delete their plans. |
| `offline_access` | A refresh token.                               |

## Exchange

`POST https://simplehouseplanner.com/api/auth/oauth2/token` with the code and your PKCE verifier, and again `resource=https://simplehouseplanner.com/mcp`. You get an access token, and a refresh token if you asked for `offline_access`.

## Use credential

Send `Authorization: Bearer <token>` with each request to the resource. Access tokens name the resource as their audience, and the server refuses a token for any other audience.

## Errors

- An invalid token gets `401` with a `WWW-Authenticate` header that names the resource metadata. Get a new token.
- A tool that needs a scope you do not have returns an error result that names the same metadata, in `_meta["mcp/www_authenticate"]`. Ask the person again.
- Above 120 calls a minute, the server answers `429` with `Retry-After`.

## Revocation

The person can disconnect a client on https://simplehouseplanner.com/account/. This ends its refresh tokens, and the server then refuses its access tokens. A client can revoke its own tokens at `https://simplehouseplanner.com/api/auth/oauth2/revoke` (RFC 7009).

## More

- Tools and the plan script API: https://simplehouseplanner.com/developers/
- Questions: support@simplehouseplanner.com