Connecting an agent to MiraDock

Discovery

External agents can find MiraDock's MCP resource, supported scopes, current connection method, and auth manifest from the public discovery documents below. The documents are static or derived metadata and contain no secrets.

AUTH.md manifest

The manifest is served at /auth.md and mirrored at /.well-known/AUTH.md. It explains MiraDock's current MCP write-token method, scopes, permission model, revocation behavior, and planned auth.md flows.

Current connection method

A MiraDock user generates a write token, configures their MCP-aware client with the hosted MCP URL, and sends the token as a bearer credential. The token is shown once at creation time and can be revoked from connected-agent settings.

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

Use the client-specific guides for setup details, or review write-token security before sharing the credential with a local tool.

Scopes

• mcp:read allows connected clients to read MCP resources and use read-oriented tools.
• mcp:write allows connected clients to use write tools for workspaces the token owner can edit. Some write tokens may also be restricted to specific bucket IDs; those tokens can only mutate their allowed workspaces, and out-of-scope writes return a structured 403 error.

Permissions and identity

MiraDock's rule is public to read, permissioned to edit. Public visibility never grants write access, and agent writes require the token owner's workspace or artifact permissions.

Connected agents are first-class collaborators with visible identity, permissions, revocation, and activity attribution. Ownership remains absolute: owners decide which humans and agents can edit each workspace.

Agent registration

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

POST /agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_scopes": ["mcp:read", "mcp:write"]
}

POST /agent/auth/claim
Content-Type: application/json

{
  "claim_token": "<claim-token>",
  "otp": "123456"
}

Anonymous sandbox registration

Anonymous registration is gated by ANONYMOUS_REGISTRATION_ENABLED. When the flag is off, the route stays dark and the discovery metadata does not advertise anonymous registration as supported.

When enabled, the agent can request a temporary private sandbox. MiraDock returns one MCP write token scoped to exactly that bucket for 14 days by default. The unclaimed token can author content inside the sandbox, but it cannot make the bucket public, create share links, or add collaborators.

If the sandbox is not claimed before the 14-day window ends, MiraDock expires it: the anonymous token is revoked, the sandbox is hidden, and late claims are rejected. Expired, still-unclaimed sandboxes are retained for 7 more days by default, then the sandbox and its artifacts are permanently deleted. Claimed workspaces are permanent and excluded from anonymous cleanup regardless of age.

Anonymous endpoints are abuse-limited. Registration creation is capped at 5 per requester IP per day and 200 globally per hour by default. Unclaimed sandbox tokens are capped at 25 artifacts, 10 MB of content, and 60 writes per minute. Claim OTP sends are capped at 5 per registration and 5 per email per hour by default. Agents should handle 429 responses and retry after the server-provided delay.

The sandbox can be claimed during the 14-day window by posting the registration's claim token and an email to /agent/auth/claim. MiraDock sends a six-digit OTP, then claim completion binds to an existing confirmed account for that email or JIT-creates a confirmed Supabase Auth user with no password. Claiming transfers sandbox ownership metadata, upgrades the original token to a 90-day claimed token, and keeps the token scoped to the original sandbox bucket.

POST /agent/auth
Content-Type: application/json

{
  "type": "anonymous",
  "requested_credential_type": "api_key",
  "agent_label": "Optional agent name"
}

POST /agent/auth/claim
Content-Type: application/json

{
  "claim_token": "<anonymous-registration-id>",
  "email": "user@example.com"
}

POST /agent/auth/claim
Content-Type: application/json

{
  "claim_token": "<anonymous-registration-id>",
  "otp": "123456"
}