# RealYield auth.md

How AI agents get and use credentials for RealYield (https://www.realyield.co.uk), a UK buy-to-let analysis site.

## Who this is for

AI agents and MCP hosts (ChatGPT, Claude and other MCP clients) acting for a person who uses RealYield.

## What needs a credential

Almost nothing. These need no credential, API key or registration:

- `GET https://www.realyield.co.uk/api/locations`: Average rental yields by area
- `GET https://www.realyield.co.uk/api/net-yield-index`: Net Yield Index
- `GET https://www.realyield.co.uk/api/search`: Site content index
- `GET https://www.realyield.co.uk/api/health`: Health check
- Every tool on the MCP server at https://www.realyield.co.uk/mcp except `check_deal`
- Every page, including its markdown copy (send `Accept: text/markdown`)

One MCP tool needs a signed-in RealYield account: `check_deal` (Deal Check). Each run reads about a dozen public data sources, so, as on the website, it needs a free account and is limited to 10 checks a minute per account.

API reference: https://www.realyield.co.uk/developers

## Discovery

- Protected resource metadata (RFC 9728): https://www.realyield.co.uk/.well-known/oauth-protected-resource/mcp
  - `resource`: https://www.realyield.co.uk/mcp
  - `authorization_servers`: https://clerk.realyield.co.uk
  - `scopes_supported`: profile
  - `bearer_methods_supported`: header
- Authorization server metadata (RFC 8414): https://clerk.realyield.co.uk/.well-known/oauth-authorization-server
- Calling `check_deal` without a token returns HTTP 401 with `WWW-Authenticate: Bearer` and a `resource_metadata` parameter pointing at the document above. ChatGPT gets the same challenge in the tool result's `_meta["mcp/www_authenticate"]`.

## Registration

- Supported method: OAuth Client ID Metadata Document. Your `client_id` is an HTTPS URL serving a JSON document that describes your client, including its redirect URIs. The authorization server fetches it the first time it sees your client. There is no registration endpoint, no dynamic client registration and no client secret.
- Clients are public (`token_endpoint_auth_method` `none`) and must use PKCE with `S256`.
- An agent cannot create an account by itself. There is no anonymous, verified email or identity assertion (ID-JAG) registration. The person signs up for, or signs in to, their own free RealYield account during authorisation, then approves the consent screen.

## Getting a token

1. Send the person to `https://clerk.realyield.co.uk/oauth/authorize` (authorization code flow, PKCE `S256`, scope `profile`, and `resource=https://www.realyield.co.uk/mcp` as the MCP authorization spec asks).
2. Exchange the code at `https://clerk.realyield.co.uk/oauth/token`. A refresh token comes back too, because the authorization server always adds `offline_access`.
3. Refresh at the same endpoint with `grant_type=refresh_token`.
4. Revoke at `https://clerk.realyield.co.uk/oauth/token/revoke` when the person disconnects you.

## Using the credential

- Send `Authorization: Bearer <access token>` on requests to https://www.realyield.co.uk/mcp. Only the header is accepted: not a query string or a form field. The header must be exactly `Bearer`, one space, then the token.
- A token issued for a different resource is refused.
- The token only identifies the account, for rate limiting. The tools read nothing else about the person and store nothing.

## Limits

- 300 requests a minute per IP address on https://www.realyield.co.uk/mcp, then HTTP 429 with `Retry-After`.
- `check_deal`: 10 a minute per account.

## Contact

https://www.realyield.co.uk/contact

This file: https://www.realyield.co.uk/auth.md