Macula MCP

Overview Schema Source Related Servers Discussions Admin

mesh_join_realm

Join the io.macula realm by binding your agent's identity to a person's account. Returns a sign-in link and QR; after confirmation, issues org identity, realm certificate, refresh token, and membership UCAN.

Instructions

Join the io.macula realm as this agent: bind this server's identity (its node_id / citizen_did) to a person's account through macula-realm. Returns a link and a QR code the person opens or scans, signs in, and confirms; it then issues an org identity, a realm certificate, a refresh token, and a membership UCAN (io.macula as issuer, this identity as audience) for this identity, stored under ~/.config/macula-mcp/realm/. Two-step by nature: the first call returns the link (and keeps polling in the background); a later call with wait_seconds picks up the outcome, which also shows in mesh://identity. Already joined: reports the membership. The UCAN is what a realm-gated capability checks -- an older realm that hasn't shipped it yet still completes the join, just without one.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "mesh_join_realm"
  }
}

Input Schema

Name	Required	Description	Default
`wait_seconds`	No	After creating (or reusing) the session, wait this long for the person to confirm before returning. 0 (default) returns the link immediately. A session lives 10 minutes.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.28.7Sep 9, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full responsibility—and it delivers: it discloses the two-step asynchronous nature, background polling, filesystem storage under ~/.config/mesh, issuance of credentials/UCAN, the already-joined behavior, and the older-realm fallback where no UCAN is issued. Side effects and statefulness are clearly visible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then flows naturally into the mechanism, storage, polling, and edge behaviors. Despite the density, every clause adds information; there is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a side-effecting, async, stateful operation with no output schema, the description covers what an agent needs: the initial return value, how to poll, where state persists, what gets issued, how identity UI reflects it, and the legacy-realm exception. Nothing critical is left to guesswork.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes wait_seconds well (0 returns immediately, session lasts 10 minutes), so the baseline is high. The description adds value by explaining how wait_seconds is used in a later call to collect an already-started join's outcome, which is not fully obvious from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Join the io.macula realm'), identifies the agent as the subject, and explains the binding of server identity to a person's account. The flow and artifacts issued (org identity, realm certificate, membership UCAN) make the tool's purpose unmistakable even without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: first call returns a link, subsequent calls with wait_seconds retrieve the outcome, and already-joined members get the membership back. It does not explicitly name alternatives or when not to use this tool, but the realm-joining flow is distinct enough among the siblings that an agent can route correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.