Connect

Connecting an agent to MiraDock

Discovery documents, credentials, and permissions for agents that build and publish Games.

Discovery

Agents can find MiraDock's MCP server, supported scopes, connection methods, and auth manifest from these public documents. They contain no secrets.

Path	Purpose
/.well-known/oauth-protected-resource	Protected resource metadata for the MCP server, including scopes and registration status.
/.well-known/oauth-authorization-server	OAuth authorization server metadata with the agent_auth block.
/.well-known/mcp	MCP server summary: transport, auth scheme, and current tool names.
/auth.md	Human- and agent-readable authentication manifest.
/.well-known/AUTH.md	The same manifest at a well-known path.
/mcp	The MCP endpoint. Every request needs a bearer credential.
/llms.txt, /llms-full.txt	The Game publishing workflow and the complete Game SDK spec as plain text.

The manifest at /auth.md (also at /.well-known/AUTH.md) describes the same connection methods in Markdown for agents.

Connection methods

Write token. A Creator creates a write token at /app/mcp, configures the MCP client with the MCP URL, and sends the token as a bearer credential. The token is shown once and can be revoked at any time.

mcp-request.httphttp

POST https://miradock.com/mcp
Authorization: Bearer miradock_mcp_<token>

OAuth. Clients that support MCP OAuth (such as Claude.ai and Claude Desktop connectors) discover the authorization server from the WWW-Authenticate challenge, register dynamically, and get an access token after the Creator approves the consent screen. See OAuth and write-token security.

Scopes

mcp:read lets a client read the Game SDK spec and validate Games.
mcp:write lets a client create, update, configure, and read stats for Games owned by the account. Write tokens include both scopes.

Permissions and identity

MiraDock's rule is public to read, permissioned to edit. Published Games are public to play, but only a Game's Creator can change it, and every agent call acts as the account that owns the credential. Arguments that try to name a different actor are rejected.

Agent activity is attributed to the credential that made it, and revoking the credential stops the agent immediately.

Agent registration

The verified-email flow is in preview. POST to /agent/auth starts an OTP ceremony and POST to /agent/auth/claim completes it; no token is issued before the OTP succeeds.

Flow	Status
Verified email	PREVIEW: email OTP ceremony that issues a MiraDock MCP write token.
Anonymous sandbox	PREVIEW: temporary sandbox token with a later verified-email claim.
ID-JAG assertions	PLANNED: trusted provider identity assertions; MiraDock does not mint ID-JAGs.

Anonymous sandbox

Anonymous registration is controlled by ANONYMOUS_REGISTRATION_ENABLED. When it is off, the registration route stays dark and discovery metadata does not advertise it.

When it is on, an agent can POST {"type": "anonymous"} to /agent/auth and immediately receive one sandbox write token that expires after 14 days. Before the sandbox is claimed, the token can create and update at most three draft Games within 10 MiB of content, at up to 60 writes per minute. Publishing, unlisting, leaderboards, SKUs, monetization, and stats return an error asking the agent to claim first.

To claim, POST the registration's claim token and an email address to /agent/auth/claim. MiraDock emails a six-digit code; posting the claim token with that code binds the sandbox to the existing account for that email, or creates one. The same token then keeps working for 90 days with the normal limits.

An unclaimed sandbox expires at the end of the 14-day window: the token is revoked and late claims are rejected. Its content is deleted 7 days later. Registration is limited to 5 per IP address per day and 200 globally per hour, and claim codes to 5 per registration and 5 per email per hour. Handle 429 responses by waiting for the Retry-After delay. These numbers are defaults; /auth.md shows the request and response formats.