The EHR initiates the launch by redirecting to your app's launch URL with parameters iss (FHIR base URL) and launch (opaque launch token).
Fetch [iss]/.well-known/smart-configuration to discover the authorization endpoint.
Redirect to the authorization endpoint including the launch parameter and scope containing 'launch' (not 'launch/patient'); this tells the server the launch token carries context.
After authorization code exchange, the token response includes context claims: patient, encounter, and/or user as top-level fields alongside access_token.
Use the patient value directly as the patient ID for FHIR queries; it is the logical ID of the FHIR Patient resource in context.
Decode the id_token (a JWT) to obtain the fhirUser claim, which is the relative URL of the Practitioner or Patient resource representing the logged-in user.
Known gotchas
The launch token is opaque and single-use; do not attempt to parse or re-use it; it is only meaningful to the issuing EHR's authorization server.
Not all EHR launches provide an encounter context; your app must handle missing encounter gracefully and not block its workflow on it.
The iss parameter in the launch URL must be validated against a pre-registered list of trusted FHIR endpoints; do not blindly trust arbitrary iss values to prevent open-redirect attacks.
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