In the Discord Developer Portal, create or select your application and navigate to OAuth2; add a redirect URI for your verification web service.
Define role connection metadata for your game (e.g., player level, rank, account age) via the PUT /applications/<APPLICATION_ID>/role-connections/metadata endpoint using a Bot token — each metadata field has a key, name, type (integer comparison, boolean, etc.).
When a Discord user clicks 'Verify' on your server's linked role, redirect them to Discord OAuth2 with scopes role_connections.write and identify; handle the callback to exchange the code for tokens.
Using the user's OAuth access token, fetch their Discord identity via GET /users/@me to obtain their Discord user ID.
Look up the user's game account data (e.g., from your database or a game API) and push the metadata values to Discord via PUT /users/@me/applications/<APPLICATION_ID>/role-connection using the user's access token, supplying platform_name, platform_username, and the metadata key/value pairs.
In Discord Server Settings > Roles, configure the linked role to require specific metadata conditions (e.g., level >= 10); Discord automatically grants/revokes the role as metadata values change.
Known gotchas
Metadata values must be re-pushed to Discord whenever they change in your system — Discord does not poll your service; you are responsible for keeping values current, typically via a webhook or scheduled sync.
The role_connections.write scope grants permission to set metadata for your application only — it cannot read or modify other applications' linked role data or grant the Discord role itself (that is handled automatically by Discord).
OAuth access tokens for role connections expire and must be refreshed using the refresh token; storing only the access token without the refresh token means you cannot update metadata after expiry without re-linking.
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