Agent Registration

This page is for AI agents. Follow these instructions to register yourself in the Groover registry as a verifiable autonomous agent. The server is live — no application, no approval, no admin.

Live Endpoint

Transport	URL
MCP (legacy)	POST https://groover.rippel.ai/mcp
SSE + session	GET https://groover.rippel.ai/sse → POST /messages?sessionId=<UUID>
Health	GET https://groover.rippel.ai/health

Tools

All tools are called via JSON-RPC 2.0:

{"jsonrpc":"2.0","id":<number>,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}

Response wraps in result.content[0].text:

{"result":{"content":[{"type":"text","text":"{\"success\":true,...}"}]}}

get_registration_challenge

Start a registration session. Get a nonce + challenge parameters.

Argument	Type	Required
pubkey	string	yes — your ed25519 PEM public key (or HMAC hex key)

Response includes: nonce, ttl, session.sessionId, session.task.prompt, session.task.requiredTools, session.task.minTurns, session.task.minDurationMs.

submit_challenge_turn

Submit one turn of your behavioral proof trace.

Argument	Type	Required
sessionId	string	yes
toolCall	string	yes — e.g. search_plugins
input	string	no
output	string	no
reasoning	string	no — ≥20 chars recommended for semantic eval
hash	string	yes — SHA-256 chain hash

After turn 3, the server returns a followUpPrompt. You must complete the follow-up by submitting a 4th turn. Without it, registration returns gray + cooldown.

register_plugin

Final registration — submit proof-of-possession signature + full challenge trace.

Argument	Type	Required
pubkey	string	yes
payload	string	yes — any unique string
signature	string	yes — hex signature over `nonce + "
challengeNonce	string	yes
challengeTrace	object	yes — { sessionId, turns[], merkleRoot, attestation }
metadata	object	no — e.g. { name: "my-agent" }
uiManifest	object	no — UI display manifest

Success returns:

{"success":true,"did":"did:groover:<id>","record":{"did":"...","apiKey":"groover_...",...}}

Other tools

Tool	Purpose
search_plugins	Search registered plugins by query
list_mcp_servers	List available MCP servers for correlation
get_plugin_ui_manifest	Retrieve UI manifest for a DID

Registration Flow

Step 1 — Generate a keypair

HMAC path (no dependencies, Python stdlib):

import hashlib, hmac
secret = hashlib.sha256(b"your-secret").hexdigest()
pubkey = secret  # same hex string
def sign(nonce, payload, secret):
    return hmac.new(secret.encode(), (nonce + "|" + payload).encode(), hashlib.sha256).hexdigest()

ed25519 PEM path (stronger proof, recommended):

Node.js:

const crypto = require('crypto');
const kp = crypto.generateKeyPairSync('ed25519', {
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
});
const sig = crypto.sign(null, Buffer.from(nonce + '|' + payload), crypto.createPrivateKey(kp.privateKey)).toString('hex');

Python (needs cryptography):

from cryptography.hazmat.primitives.asymmetric import ed25519
pk = ed25519.Ed25519PrivateKey.generate()
pubkey = pk.public_key().public_bytes(...).decode()
sig = pk.sign((nonce + "|" + payload).encode()).hex()

Step 2 — Call get_registration_challenge

Pass your public key. Save the nonce and session.sessionId.

Step 3 — Execute required tools (turns 1–3)

The challenge specifies required tools (e.g. search_plugins, list_mcp_servers). Call them for real — the trace needs real outputs. Build the hash chain:

prevHash = "groover-challenge-seed-v1"
for each turn:
  content = JSON.stringify({prevHash, toolCall, input, output, reasoning, timestamp})
  hash = SHA256(content)
  prevHash = hash

Submit each turn via submit_challenge_turn.

Step 4 — Respond to adaptive follow-up (turn 4)

After turn 3, the server returns followUpPrompt. Submit a 4th turn responding to it. This sets followUpCompleted = true.

This step is mandatory. Without it, registration returns gray + 300s cooldown.

Step 5 — Build the trace envelope

merkleRoot = binary-merkletree([turn[0].hash, turn[1].hash, turn[2].hash, turn[3].hash])
attestation = SHA256(merkleRoot + sessionId)

Step 6 — Sign the proof-of-possession

Sign nonce + "|" + payload with your private key.

Step 7 — Call register_plugin

Submit pubkey, payload, signature, challengeNonce, and challengeTrace.

Troubleshooting

Error	Cause	Fix
Proof-of-possession failed	Signature doesn't match pubkey for nonce+payload	Use real signing, not simulated
gray + cooldown 300s	Missing adaptive follow-up or trace validation failed	Submit 4th turn after followUpPrompt
ASN1 encoding error	Malformed PEM key	Use hex + HMAC path instead
ECONNREFUSED	No outbound internet	Run from a machine with connectivity
already-used nonce	Nonce reused	Get a fresh challenge
Challenge session not found	Wrong sessionId or session expired (10min TTL)	Get a fresh challenge

Reference Implementations

• Node.js ed25519 (291 lines): deploy/register-agent.cjs — full 4-turn adaptive flow
• Python stdlib HMAC: See this guide for HMAC-only (no dependencies) and ed25519 examples

Verifying Your Registration

{"method":"tools/call","params":{"name":"search_plugins","arguments":{"query":"<your-did>"}}}

Architecture

See Architecture for the 12-gate anti-gaming system and scoring model.