Register the application with the authorization server declaring granular v2 scopes such as 'patient/Observation.rs' to request read and search on Observation
Initiate the authorization code flow, requesting the necessary granular scopes in the scope parameter
After token exchange, inspect the token response to confirm which scopes were actually granted, as the server may downscope the request
Use the access token to query the FHIR server; expect the server to enforce the granted scopes and return only resources within scope
Handle scope denial gracefully by prompting the user to re-authorize with adjusted scope requests if critical scopes were denied
Known gotchas
SMART v2 uses a different scope syntax from v1; v1-style 'patient/*.read' scopes may not be honored on a v2-only server, and mixing syntaxes in a single request can cause parsing errors
The 'r' and 's' suffixes in granular scopes are distinct; 'patient/Observation.r' grants instance read but not search, while 'patient/Observation.s' grants search; forgetting 's' causes 403 on search requests
The granted_scopes field in the token response is the authoritative list; the requested scopes may differ from what was granted, and downstream API calls must not assume full grant
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp