# Auth.md — Agent Access & Authentication for https://buildingbettersoftware.io

This site runs a real, minimal MCP (Model Context Protocol) server for AI
agents, plus an OAuth 2.0 token service protecting its write tier.

## Endpoints

| What | URL |
|---|---|
| MCP endpoint (Streamable HTTP JSON-RPC, POST) | https://buildingbettersoftware.io/mcp |
| OAuth 2.0 token endpoint (client_credentials) | https://buildingbettersoftware.io/oauth/token |
| Authorization server metadata (RFC 8414) | https://buildingbettersoftware.io/.well-known/oauth-authorization-server |
| Protected resource metadata (RFC 9728) | https://buildingbettersoftware.io/.well-known/oauth-protected-resource |
| MCP server card | https://buildingbettersoftware.io/.well-known/mcp/server-card.json |
| A2A agent card (describes the MCP interface) | https://buildingbettersoftware.io/.well-known/agent-card.json |

## Access tiers

**Public (no auth):** `initialize`, `tools/list`, and the read-only tools
`list_services`, `get_page_content`, `search_content`.

**Bearer-protected:** the `contact_request` tool (it has a real side effect:
stores the inquiry and emails the site owner). Requires scope
`mcp:tools:write`. Rate-limited to 5 requests/hour/IP.

## Getting a token (demo tier)

A demo client is published here on purpose so agents can exercise the full
OAuth flow end-to-end. It grants only `mcp:tools:write` on this endpoint and
is rate-limited; rotate/revoke happens server-side without notice.

```
curl -X POST https://buildingbettersoftware.io/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=demo-agent \
  -d client_secret=bbs-demo-2026-K3vR8mQx
```

Response: `{"access_token":"...","token_type":"Bearer","expires_in":3600,...}`

## Example: full round trip

```
# 1. Discover tools (public)
curl -X POST https://buildingbettersoftware.io/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 2. Call a public tool
curl -X POST https://buildingbettersoftware.io/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_services","arguments":{}}}'

# 3. Call the protected tool with a bearer token
curl -X POST https://buildingbettersoftware.io/mcp -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"contact_request","arguments":{"name":"Jane Agent","email":"jane@example.com","message":"Interested in agent workflow consulting."}}}'
```

Unauthenticated calls to `contact_request` return HTTP 401 with a
`WWW-Authenticate` header pointing at the protected-resource metadata, per
RFC 9728.

## Registration (Auth.md profile — anonymous self-registration)

Self-serve anonymous registration is live and issues REAL credentials that
authenticate at the token endpoint:

```
# 1. Register (no identity required) — returns client_id + client_secret
curl -X POST https://buildingbettersoftware.io/agent/register

# 2. Exchange the issued credentials for a bearer token
curl -X POST https://buildingbettersoftware.io/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=<client_id from step 1> \
  -d client_secret=<client_secret from step 1>
```

Anonymous credentials get the same demo-tier scope (`mcp:tools:write`) and
rate limits. To claim/upgrade an anonymous identity (human-reviewed):

```
curl -X POST https://buildingbettersoftware.io/agent/claim -H 'Content-Type: application/json' \
  -d '{"client_id":"anon-...","email":"you@example.com","note":"who you are"}'
```

Machine-readable registration metadata lives in the `agent_auth` block of
https://buildingbettersoftware.io/.well-known/oauth-authorization-server per the Auth.md profile
(https://github.com/workos/auth.md).

For a non-demo client credential (higher rate limits, stable secret),
contact the site owner via https://buildingbettersoftware.io/contact/ or use `contact_request`.