@reclaimprotocol/agent 0.1.33 → 0.1.34

package/lib/mcp/tools/agent/start-integration.d.ts

@@ -0,0 +1,15 @@
+import { type RegisteredTool } from '../../server.ts';
+interface StartIntegrationArgs {
+    goal: string;
+    orgId?: string;
+    providerIds?: string[];
+}
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export declare function startIntegrationTool(): RegisteredTool;
+/** Fill the plan template. Exported for tests. */
+export declare function renderStartIntegration(args: StartIntegrationArgs): string;
+export {};

package/lib/mcp/tools/agent/start-integration.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { defineTool } from "../../server.js";
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export function startIntegrationTool() {
+    return defineTool({
+        name: 'start_integration',
+        description: 'Returns a step-by-step plan for adding Reclaim verification to the '
+            + 'current codebase: sign in, build or choose a provider, then add the '
+            + 'session route, callback, and Verify button. Call it first when a '
+            + 'developer wants their users to prove something, and follow the '
+            + 'plan to the end. Changes nothing itself.',
+        inputSchema: {
+            type: 'object',
+            required: ['goal'],
+            properties: {
+                goal: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 300,
+                    description: 'What the developer\'s users prove, for example, "they have '
+                        + 'a GitHub account with 100 followers".',
+                },
+                orgId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'Organization to use. Omit to choose from the list.',
+                },
+                providerIds: {
+                    type: 'array',
+                    maxItems: 10,
+                    items: { type: 'string' },
+                    description: 'Existing provider IDs to use. Omit to build a new provider.',
+                },
+            },
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => renderStartIntegration(args));
+}
+/** Fill the plan template. Exported for tests. */
+export function renderStartIntegration(args) {
+    const providerIds = args.providerIds?.length
+        ? args.providerIds.map((id) => `\`${id}\``).join(', ')
+        : undefined;
+    const values = {
+        goal: args.goal,
+        orgId: args.orgId,
+        providerIds,
+    };
+    const template = readFileSync(fileURLToPath(new URL('../../../../skill/start-integration.md', import.meta.url)), 'utf8');
+    return template
+        // Keep a conditional block only when its input was given (or not given).
+        .replace(/<!-- (if|ifnot):(\w+) -->\n([\s\S]*?)<!-- endif -->\n/g, (_, kind, name, body) => {
+        return (kind === 'if') === Boolean(values[name]) ? body : '';
+    })
+        .replace(/\{\{(\w+)\}\}/g, (_, name) => values[name] ?? '');
+}

package/lib/mcp/tools/authenticate/authenticate.js

@@ -16,18 +16,16 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
                 + 'get_me_providers; those need the separate old-devtools login, '
                 + 'reclaim_authenticate. Check both with get_devtools_mode. '
             : '')
-            + 'Authorize the CLI / MCP to make authenticated API calls. Opens '
-            + 'the '
-            + 'browser to the builder sign-in page (standard OAuth 2.0 ' +
-            'authorization-code + PKCE with a localhost redirect) and waits for ' +
-            'the user to sign in and approve. On success the access token is ' +
-            'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
-            'Call with no arguments. This bearer token authenticates ' +
-            'dashboard/org-management calls (for example, list_orgs, or ' +
-            'issuing an org secret). Programmatic verification calls use a ' +
-            'separate org secret ' +
-            '(rorg_…, set as RECLAIM_ORG_SECRET).',
+            + 'Signs the developer in to Builder. Opens the Builder sign-in page '
+            + 'in their browser (OAuth 2.0 authorization code with PKCE, '
+            + 'redirecting to a localhost port this server opens) and waits for '
+            + 'them to approve. Saves the access token in ~/.reclaim/config.json '
+            + 'with mode 0600 and uses it for this session; the token is never '
+            + 'returned. The token authorizes organization-management tools such '
+            + 'as `list_orgs`. Programmatic verification tools use a separate '
+            + 'organization key; see `issue_org_token`. Call with no arguments.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { openWorldHint: true, idempotentHint: true },
     }, async () => runOAuthLoopback(client));
 }
 const _customFetchForOauth = async (url, options) => {

package/lib/mcp/tools/authenticate/build.js

@@ -1,6 +1,7 @@
 import { authenticateTool } from "./authenticate.js";
 import { importTool } from "./import.js";
 import { issueTool } from "./issue.js";
+import { issueOrgTokenTool } from "./issue-org-token.js";
 import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
 /**
  * Local-only key tools — no backend client needed. These manage the eth
@@ -23,6 +24,7 @@ export function buildLocalCredentialTools() {
 export function buildCredentialTools(client) {
     return [
         authenticateTool(client),
+        issueOrgTokenTool(client),
         ...buildLocalCredentialTools(),
     ];
 }

package/lib/mcp/tools/authenticate/builder-access.js

@@ -26,6 +26,7 @@ export function buildBuilderOrganizationTools(client) {
                     cursor: { type: 'string', maxLength: 500 },
                 },
             },
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async ({ cursor }) => {
             const { data } = await client.call('ListOrgs', {
                 query: { ...(cursor ? { cursor } : {}) },

package/lib/mcp/tools/authenticate/eth-key.d.ts

@@ -19,6 +19,14 @@ export declare function normalizeEthHex(value: string): string;
  * ask for one (see `resolve_owner_key`).
  */
 export declare function resolveEthKey(projectDir?: string): ResolvedEthKey | undefined;
+/** Append `entry` to the project `.gitignore` if not already present. */
+export declare function ensureGitignored(projectDir: string, entry: string): void;
+/**
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
+ */
+export declare function upsertEnvVar(projectDir: string, envFile: string, name: string, value: string): string;
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).

package/lib/mcp/tools/authenticate/eth-key.js

@@ -16,8 +16,8 @@
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
 import assert from 'node:assert';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { privateKey, privateKeyFile } from "../../../consts.js";
 import { findProjectRoot } from "../../../paths.js";
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY';
@@ -80,7 +80,7 @@ export function resolveEthKey(projectDir = findProjectRoot(process.cwd())) {
     return undefined;
 }
 /** Append `entry` to the project `.gitignore` if not already present. */
-function ensureGitignored(projectDir, entry) {
+export function ensureGitignored(projectDir, entry) {
     const path = join(projectDir, '.gitignore');
     const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
     if (current.split('\n').some((l) => l.trim() === entry)) {
@@ -90,26 +90,38 @@ function ensureGitignored(projectDir, entry) {
     writeFileSync(path, current + prefix + entry + '\n');
 }
 /**
- * Persist a raw eth private key to the project `.env` as
- * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
- * Used by `issue_credentials` (generate) and `import_credentials` (supplied
- * hex). Returns the derived address and the `.env` path.
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
  */
-export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.cwd())) {
-    const hex = normalizeEthHex(privateKeyHex);
-    const envPath = join(projectDir, ENV_FILE);
-    const line = `${ENV_VAR}=${hex}`;
+export function upsertEnvVar(projectDir, envFile, name, value) {
+    const envPath = resolve(projectDir, envFile);
+    const line = `${name}=${value}`;
     const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
-    const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm');
+    const re = new RegExp(`^\\s*${name}\\s*=.*$`, 'm');
     let next;
     if (re.test(existing)) {
-        next = existing.replace(re, line);
+        // A function replacer keeps `$` sequences in the value literal.
+        next = existing.replace(re, () => line);
     }
     else {
         const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
         next = existing + prefix + line + '\n';
     }
+    mkdirSync(dirname(envPath), { recursive: true });
     writeFileSync(envPath, next, { mode: 0o600 });
-    ensureGitignored(projectDir, ENV_FILE);
-    return { path: envPath, address: deriveFromPrivateKey(hex).address };
+    chmodSync(envPath, 0o600);
+    ensureGitignored(projectDir, relative(projectDir, envPath));
+    return envPath;
+}
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.cwd())) {
+    const hex = normalizeEthHex(privateKeyHex);
+    const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex);
+    return { path, address: deriveFromPrivateKey(hex).address };
 }

package/lib/mcp/tools/authenticate/import.js

@@ -5,53 +5,40 @@ import { writeEthKey } from "./eth-key.js";
 export function importTool() {
     return defineTool({
         name: 'import_credentials',
-        description: 'Import an eth proof-owner key the dev already holds and persist it ' +
-            'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
-            'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
-            'The address is derived locally; the private key is never ' +
-            'returned. This is a local signing key only (not registered ' +
-            'with any server, ' +
-            'unrelated to org auth or encryption).',
+        description: 'Imports an eth proof-owner key from a file the developer already '
+            + 'holds. Reads the raw 0x-hex key from `keyFile` and writes it to '
+            + 'the project `.env` as RECLAIM_PRIVATE_KEY (mode 0600; `.env` '
+            + 'added to .gitignore). Returns the derived address and the `.env` '
+            + 'path; never the key. The key is a local signing key only: it is '
+            + 'not registered with any server and is unrelated to org auth or '
+            + 'encryption. To create a new key instead, use `issue_credentials`.',
         inputSchema: {
             type: 'object',
+            required: ['keyFile'],
             properties: {
-                privateKey: {
-                    type: 'string',
-                    pattern: '^0x?[0-9a-fA-F]{64}$',
-                    description: 'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
-                },
                 keyFile: {
                     type: 'string',
-                    description: 'Path to a file containing the raw 0x-hex private key ' +
-                        '(absolute or project-relative).',
+                    description: 'Path to a file containing the raw 0x-hex private key '
+                        + '(absolute or relative to the working directory).',
                 },
                 projectDir: {
                     type: 'string',
-                    description: 'Project directory whose `.env` the key is written to. ' +
-                        'Defaults to the closest ancestor of cwd containing .git or ' +
-                        'package.json.',
+                    description: 'Project directory whose `.env` the key is written to. '
+                        + 'Defaults to the closest ancestor of cwd containing .git or '
+                        + 'package.json.',
                 },
             },
         },
+        annotations: { readOnlyHint: false, destructiveHint: false },
     }, async (args) => {
-        if (!args.privateKey && !args.keyFile) {
-            throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.');
-        }
-        if (args.privateKey && args.keyFile) {
-            throw new Error('Provide only one of `privateKey` or `keyFile`.');
-        }
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
-        const privateKeyHex = args.keyFile
-            ? readFileSync(args.keyFile, 'utf8')
-            : args.privateKey;
-        const { path, address } = writeEthKey(privateKeyHex, projectDir);
+        const { path, address } = writeEthKey(readFileSync(args.keyFile, 'utf8'), projectDir);
         return {
             address,
             path,
-            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
-                '(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
-                'secret — it has been added to .gitignore.',
+            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY '
+                + '(mode 0600). resolve_owner_key resolves it from .env. Keep .env '
+                + 'secret: it has been added to .gitignore.',
         };
     });
 }

package/lib/mcp/tools/authenticate/issue-org-token.d.ts

@@ -0,0 +1,8 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export declare function issueOrgTokenTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/tools/authenticate/issue-org-token.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { defineTool } from "../../server.js";
+import { upsertEnvVar } from "./eth-key.js";
+import { saveOrgKey } from "./org-key-store.js";
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export function issueOrgTokenTool(client) {
+    return defineTool({
+        name: 'issue_org_token',
+        description: 'Issues an organization API key (owner only) and writes it to a '
+            + 'server env file in the project, so the app can read it at runtime. '
+            + 'Also saves it on this machine for the org-key tools. Returns the '
+            + 'org, file, variable, and last four characters; never the key. '
+            + 'Replaces an existing variable of the same name in the file. '
+            + 'Adds the file to .gitignore. Use when the app needs a key, or '
+            + 'before `create_verification_session`.',
+        inputSchema: {
+            type: 'object',
+            required: ['orgId', 'projectDir'],
+            properties: {
+                orgId: { type: 'string', format: 'uuid' },
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the app\'s project directory.',
+                },
+                envFile: {
+                    type: 'string',
+                    description: 'Env file to write, relative to `projectDir`. Default `.env`.',
+                },
+                envVar: {
+                    type: 'string',
+                    pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+                    description: 'Variable name to set. Default `RECLAIM_ORG_SECRET`.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async (args) => {
+        assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
+        const envFile = args.envFile || '.env';
+        const envVar = args.envVar || 'RECLAIM_ORG_SECRET';
+        const inside = relative(args.projectDir, resolve(args.projectDir, envFile));
+        assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
+        const { data } = await client.call('IssueOrgToken', {
+            params: { orgId: args.orgId },
+        });
+        const path = upsertEnvVar(args.projectDir, envFile, envVar, data.orgSecret);
+        saveOrgKey(args.orgId, data.orgSecret);
+        return {
+            orgId: args.orgId,
+            envFile: path,
+            envVar,
+            last4: data.last4,
+        };
+    });
+}

package/lib/mcp/tools/authenticate/issue.js

@@ -5,15 +5,14 @@ import { writeEthKey } from "./eth-key.js";
 export function issueTool() {
     return defineTool({
         name: 'issue_credentials',
-        description: 'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
-            'that signs local claim creation) and write the raw private key to ' +
-            'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
-            'registered with any server and is unrelated to org auth (the org ' +
-            'secret) or encryption (the eth decrypt key). ALWAYS confirm with ' +
-            'the dev before generating a new key. After writing, run_proof picks ' +
-            'it up automatically via resolve_owner_key. The private key is never ' +
-            'returned in the response.',
+        description: 'Generates a new secp256k1 eth proof-owner key and writes the '
+            + 'private key to the project `.env` as RECLAIM_PRIVATE_KEY (mode '
+            + '0600; `.env` added to .gitignore). Returns the address and the '
+            + '`.env` path; never the key. The key is a local signing key only: '
+            + 'it is not registered with any server and is unrelated to org auth '
+            + 'or encryption. Confirm with the developer before replacing an '
+            + 'existing key. `run_proof` then picks it up through '
+            + '`resolve_owner_key`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -25,6 +24,7 @@ export function issueTool() {
                 },
             },
         },
+        annotations: { destructiveHint: false },
     }, async (args) => {
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
         const keypair = generateKeypair();

package/lib/mcp/tools/authenticate/org-key-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export declare function saveOrgKey(orgId: string, secret: string): void;
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export declare function savedOrgKey(orgId?: string): string | undefined;

package/lib/mcp/tools/authenticate/org-key-store.js

@@ -0,0 +1,23 @@
+import { ConfigStore } from "../../../config/store.js";
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export function saveOrgKey(orgId, secret) {
+    const saved = new ConfigStore().read()?.org_keys;
+    new ConfigStore().write({
+        org_keys: {
+            byOrg: { ...saved?.byOrg, [orgId]: secret },
+            recent: orgId,
+        },
+    });
+}
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export function savedOrgKey(orgId) {
+    const saved = new ConfigStore().read()?.org_keys;
+    const id = orgId || saved?.recent;
+    return id ? saved?.byOrg[id] : undefined;
+}

package/lib/mcp/tools/authenticate/resolve-owner-key.js

@@ -16,18 +16,16 @@ import { ENV_FILE, resolveEthKey } from "./eth-key.js";
 export function resolveOwnerKeyTool() {
     return defineTool({
         name: 'resolve_owner_key',
-        description: 'Resolve which eth proof-owner key run_proof should sign with — ' +
-            'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
-            'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
-            'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
-            'Returns { ready: true, address, source } when one is ' +
-            'available — pass `address` to run_proof as `ownerAddress`. ' +
-            'Returns { ready: false } ' +
-            'when none exists: then ask the dev to generate one ' +
-            '(issue_credentials) or import one they already hold ' +
-            '(import_credentials, accepts 0x-hex or a key-file path), and call ' +
-            'resolve_owner_key again. Never exposes the private key.',
+        description: 'Finds the eth proof-owner key `run_proof` signs with. Call it '
+            + 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
+            + 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
+            + 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
+            + '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
+            + 'ready: false } when none exists: ask the developer to create one '
+            + 'with `issue_credentials` or import one with `import_credentials` '
+            + '(a key file), then call it again. Never returns the key.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => {
         const projectDir = findProjectRoot(process.cwd());
         const resolved = resolveEthKey(projectDir);
@@ -45,7 +43,7 @@ export function resolveOwnerKeyTool() {
                 `env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
                 'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
                 'issue_credentials, or import one they already hold via ' +
-                'import_credentials (0x-hex or a key-file path). Then call ' +
+                'import_credentials (a key file). Then call ' +
                 'resolve_owner_key again and pass its address to run_proof as ' +
                 'ownerAddress.',
         };

package/lib/mcp/tools/mode/mode.js

@@ -44,6 +44,7 @@ export function buildModeTools(config, currentOldMode) {
                 },
                 required: ['mode'],
             },
+            annotations: { openWorldHint: false, idempotentHint: true },
         }, async (parsed) => {
             config.write({ mode: parsed.mode });
             const restartRequired = parsed.mode !== current;
@@ -71,6 +72,7 @@ export function buildModeTools(config, currentOldMode) {
                 + 'the staleness with an error naming the tool to re-run. Which '
                 + 'login authorizes what: how_it_works({ topic: "auth" }).',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async () => {
             const persisted = config.read()?.mode;
             const oldIdentity = config.read()?.old_devtools;

package/lib/mcp/tools/verification/result.js

@@ -3,6 +3,7 @@ import assert from 'node:assert';
 import { apiUrl, orgSecret } from "../../../consts.js";
 import { defineTool } from "../../server.js";
 import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
+import { savedOrgKey } from "../authenticate/org-key-store.js";
 /** Statuses that can carry a Builder-managed terminal result. */
 const TERMINAL = new Set([
     'success',
@@ -25,11 +26,10 @@ const RESULT_EVENTS = new Set([
  * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
 function resolveOrgSecret(orgToken) {
-    const secret = orgToken?.trim() || orgSecret()?.trim();
+    const secret = orgToken?.trim() || orgSecret()?.trim() || savedOrgKey();
     assert(secret, new Error('No organization API key. Verification reads authenticate with the org '
-        + 'secret (rorg_…): pass orgToken (from issue_org_token, or the '
-        + 'app\'s RECLAIM_ORG_SECRET), or export RECLAIM_ORG_SECRET for the '
-        + 'MCP server.'));
+        + 'secret (rorg_…): run issue_org_token to save a key, pass orgToken, '
+        + 'or export RECLAIM_ORG_SECRET for the MCP server.'));
     return secret;
 }
 /**
@@ -49,7 +49,8 @@ export function verificationResultTool() {
             + 'while Builder still holds it: until its callback is delivered, or '
             + '7 days undelivered. The callback is the normal way to get results. '
             + 'Authenticates with the org API key: `orgToken`, else '
-            + '`RECLAIM_ORG_SECRET`. Encrypted deliveries also require '
+            + '`RECLAIM_ORG_SECRET`, else the key saved by `issue_org_token`. '
+            + 'Encrypted deliveries also require '
             + 'the matching ETH decryption key. Returns `ready: false` until a '
             + 'payload is available. Invalid results fail verification and are not '
             + 'returned. Use `list_verification_events` to diagnose '
@@ -68,11 +69,13 @@ export function verificationResultTool() {
                     maxLength: 200,
                     description: 'The organization API key (`rorg_…`): from '
                         + '`issue_org_token`, or the app\'s RECLAIM_ORG_SECRET. '
-                        + 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET. Never echo '
-                        + 'it back to the user.',
+                        + 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET, then the '
+                        + 'key saved by `issue_org_token`. Never echo it back to the '
+                        + 'user.',
                 },
             },
         },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
         const secret = resolveOrgSecret(args.orgToken);
         // Optional eth decryption key — absent ⇒ plaintext-only.

package/lib/tools/registry.d.ts

@@ -1,8 +1,20 @@
 import type { JSONSchema } from 'zod/v4/core';
+/** MCP tool hints that let a client decide when to ask for approval. */
+export interface ToolAnnotations {
+    /** The tool never changes state. */
+    readOnlyHint?: boolean;
+    /** The tool can delete or overwrite state. */
+    destructiveHint?: boolean;
+    /** Repeating a call with the same input has no further effect. */
+    idempotentHint?: boolean;
+    /** The tool reaches systems outside this machine. */
+    openWorldHint?: boolean;
+}
 export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: JSONSchema.ObjectSchema;
+    annotations?: ToolAnnotations;
 }
 export interface RegisteredTool {
     definition: ToolDefinition;

package/lib/tools/registry.js

@@ -75,6 +75,7 @@ export function extendTool(tool, extra) {
             name: base.name,
             description: extra.description ?? base.description,
             inputSchema,
+            ...(base.annotations ? { annotations: base.annotations } : {}),
         },
         handler: tool.handler,
     };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.33",
+	"version": "0.1.34",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.1.5",
-		"@reclaimprotocol/client": "0.1.33",
+		"@reclaimprotocol/client": "0.1.34",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",