In the Discord Developer Portal, create an application and navigate to Linked Roles; define one or more role connection metadata fields (e.g., account_level as integer_greater_than_or_equal).
Register the metadata schema by sending a PUT request to the application role connection metadata endpoint using your bot token, defining each field's key, name, description, and type.
Implement an OAuth2 callback endpoint in your backend: after a user authorizes via the Discord OAuth flow with the role_connections.write scope, exchange the code for an access token.
Using the user's Discord access token, call the Update User Application Role Connection endpoint to write the user's verified metadata values (e.g., their in-game level) for your application.
In the Discord server settings, create a role and configure it to require your linked role metadata condition (e.g., account_level >= 10); Discord evaluates this metadata when assigning the role.
Refresh metadata values periodically or on game events (level-up, achievement) by re-calling the Update endpoint so Discord roles stay current with player progression.
Known gotchas
The role_connections.write scope grants only the ability to update metadata for your application; it does not allow reading other scopes' data and must be requested separately from other OAuth scopes.
Discord evaluates role eligibility only when metadata is updated; a player who loses eligibility (e.g., account banned) retains the role until your system pushes a metadata update reflecting the change.
Metadata field keys are lowercase alphanumeric with underscores and limited in length; mismatched keys between your schema registration and the update payload will result in the metadata being ignored.
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