Skip to content
Dice Monster DocsDice Monster Docs

Connect an MCP client

Dice Monster exposes an OAuth-protected Model Context Protocol server at:

https://api.dicemonster.avenceslau.com/mcp

Add that URL as a remote HTTP MCP server in a client that supports MCP OAuth. The client will open Dice Monster in your browser so you can sign in and approve access. No API key needs to be created or copied. An omitted OAuth scope means compendium:read only; clients must explicitly request both compendium:read compendium:write for write consent. Unknown, duplicate, and write-only scope requests are rejected.

Every connection can search and retrieve spells, powers, monsters, items, sources, conditions, and languages from compendium sources your Dice Monster account can already access. A read grant cannot create, edit, or delete content.

Access rollout

Section titled “Access rollout”

MCP access is currently enabled per account. If the authorization screen says that access is not enabled, ask a Dice Monster operator to enable the mcp-access-level Flagship flag for your user ID.

The active levels are:

  • none: MCP authorization and requests are denied.
  • read: read-only compendium access is enabled.
  • read-write: permits eligibility for explicit write consent, but only when the secure persistence layer and global write epoch are enabled. Flagship is eligibility rather than the sole authorization for a write grant.

Dynamically registered MCP client names and identities are unverified. The consent screen prominently warns before a write grant; approve it only for a client you trust.

When all write checks pass, the client receives three typed tools for one record at a time: create, update, or copy supported compendium content. Equipment, armor, weapons, magic items, spells, powers, and monsters are supported. Updates require the expected revision; copies become independent records owned by the caller and do not carry source relationships or advanced configuration. MCP cannot edit content owned by another user—even through sharing, campaign membership, or administrator status—and it cannot delete or bulk mutate content. General Code Mode remains read-only.

Write tools fail closed and remain undiscoverable until migration 0059 has been applied by an operator and the global write control is enabled. A read-write Flagship assignment by itself does not provide write authority.

Reconnect or revoke access

Section titled “Reconnect or revoke access”

OAuth access tokens are opaque, expire after 15 minutes, and are stored only as hashes by the authorization service. Refresh exchanges issue a replacement token and retain the immediately previous token for concurrent-refresh overlap; the grant expires after 30 days. Your client should refresh automatically and replace its stored token with each response.

To revoke a user’s MCP access, an operator can remove that user from the durable dice-monster:mcpAccessAssignments map so mcp-access-level evaluates to none. Dice Monster checks the flag on every MCP request. Flagship changes can take up to 30 seconds to propagate globally, after which previously issued access tokens stop working.

OAuth clients can also revoke their own token through the authorization server’s revocation endpoint advertised by OAuth discovery.

Operator reference

Section titled “Operator reference”
  • Flagship app: dice-monster
  • Flagship app ID: 4222e70a-de6b-44bd-a3f7-0a2ba8a97b65
  • Flag key: mcp-access-level
  • OAuth issuer: https://api.dicemonster.avenceslau.com
  • Authorization metadata: https://api.dicemonster.avenceslau.com/.well-known/oauth-authorization-server
  • Protected resource metadata: https://api.dicemonster.avenceslau.com/.well-known/oauth-protected-resource/mcp
  • Dynamic client registration: https://api.dicemonster.avenceslau.com/register
  • Token exchange and revocation: https://api.dicemonster.avenceslau.com/token
  • Default scope: compendium:read
  • Optional write consent scope pair: compendium:read compendium:write
  • Required PKCE method: S256
  • Write tools: create_owned_content, update_owned_content, copy_accessible_content
  • Writable kinds: equipment, armor, weapons, magic items, spells, powers, and monsters
  • Write argument limit: 48 KiB
  • Write budgets: 20/user/minute and 120/client/minute

OAuth grants and tokens use the backend’s dedicated OAUTH_KV namespace. The frontend never receives a token or an unvalidated client callback URL; it only carries a signed, ten-minute authorization continuation through login and consent. Consent continuations are also bound to the authenticated session. Write continuations are stored with the active epoch and consumed exactly once. Flagship failures, missing write tables, a disabled or changed epoch, unknown variants, and live downgrades all fail closed.