@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/lib/mcp/credentials/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export declare function reclaimHome(): string;
+export declare function credentialsCachePath(): string;
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export declare function findProjectRoot(start?: string): string;

package/lib/mcp/credentials/paths.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export function reclaimHome() {
+    return process.env.RECLAIM_HOME || join(homedir(), '.reclaim');
+}
+export function credentialsCachePath() {
+    return join(reclaimHome(), 'credentials.json');
+}
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export function findProjectRoot(start = process.cwd()) {
+    const markers = ['.git', 'package.json', 'pyproject.toml', 'Cargo.toml'];
+    let dir = resolve(start);
+    for (let i = 0; i < 8; i++) {
+        for (const m of markers) {
+            if (existsSync(join(dir, m))) {
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return start;
+}

package/lib/mcp/credentials/poll.d.ts

@@ -0,0 +1,27 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { components } from '../../types/openapi.gen.ts';
+type Session = components['schemas']['CredentialAttachSession'];
+type PollResult = {
+    outcome: 'linked';
+    token?: string;
+    orgId?: string;
+} | {
+    outcome: 'expired';
+} | {
+    outcome: 'timeout';
+    elapsed: number;
+    attachUrl: string;
+} | {
+    outcome: 'error';
+    message: string;
+};
+/**
+ * Poll GET /credentials/attach/sessions/{code} until the session is
+ * LINKED or we give up, whichever comes first.
+ *
+ * Errors inside the loop are surfaced immediately after MAX_CONSECUTIVE_ERRORS
+ * rather than being silently swallowed — this is what tells the agent that
+ * e.g. the confirmation POST failed or the server restarted.
+ */
+export declare function pollUntilLinked(client: ReclaimClient, session: Pick<Session, 'code' | 'attachUrl' | 'expiresAt'>, onToken?: (token: string) => void): Promise<PollResult>;
+export {};

package/lib/mcp/credentials/poll.js

@@ -0,0 +1,61 @@
+// How long to poll before giving up and telling the user what to do.
+// Shorter than the 15-min server TTL on purpose — agents can't block long.
+const POLL_TIMEOUT_MS = 3 * 60_000; // 3 minutes
+const POLL_INTERVAL_MS = 5_000; // 5 seconds
+const MAX_CONSECUTIVE_ERRORS = 5;
+/**
+ * Poll GET /credentials/attach/sessions/{code} until the session is
+ * LINKED or we give up, whichever comes first.
+ *
+ * Errors inside the loop are surfaced immediately after MAX_CONSECUTIVE_ERRORS
+ * rather than being silently swallowed — this is what tells the agent that
+ * e.g. the confirmation POST failed or the server restarted.
+ */
+export async function pollUntilLinked(client, session, onToken) {
+    const sessionExpiry = new Date(session.expiresAt).getTime();
+    const deadline = Math.min(sessionExpiry, Date.now() + POLL_TIMEOUT_MS);
+    const startedAt = Date.now();
+    let consecutiveErrors = 0;
+    while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        let polled;
+        try {
+            polled = await client.call('GetAttachSession', {
+                params: { code: session.code },
+                query: {}, body: {},
+            });
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            consecutiveErrors++;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                return {
+                    outcome: 'error',
+                    message: `Polling failed ${consecutiveErrors} times in a row: `
+                        + err.message
+                        + '. The session confirmation may have failed — try opening '
+                        + session.attachUrl
+                        + ' again and confirming, then retry.',
+                };
+            }
+            continue; // transient error, retry
+        }
+        if (polled.status === 'LINKED') {
+            const token = polled.token?.trim();
+            if (token) {
+                onToken?.(token);
+            }
+            return {
+                outcome: 'linked',
+                token,
+                orgId: polled.linkedOrgId,
+            };
+        }
+        if (polled.status === 'EXPIRED') {
+            return { outcome: 'expired' };
+        }
+        // status === 'PENDING' → keep polling
+    }
+    const elapsed = Math.round((Date.now() - startedAt) / 60_000);
+    return { outcome: 'timeout', elapsed, attachUrl: session.attachUrl };
+}

package/lib/mcp/{tools/credentials → credentials}/resolve-owner-key.d.ts

@@ -1,4 +1,4 @@
-import { type RegisteredTool } from '../../server.ts';
+import { type RegisteredTool } from '../server.ts';
 /**
  * Decide which app credential `run_proof` should sign with, BEFORE
  * calling it. `run_proof` requires an `ownerAddress` and does no

package/lib/mcp/{tools/credentials → credentials}/resolve-owner-key.js

@@ -1,6 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
 import { suggestCredentialForDir } from "./cache.js";
 import { readPrivateKeyFromEnvFile } from "./env-file.js";
 /**

package/lib/mcp/credentials/session-cache.d.ts

@@ -0,0 +1,14 @@
+export type CachedSession = {
+    token: string;
+    /** ISO timestamp when the token expires (2 days from issue). */
+    expiresAt: string;
+    /** Email of the user who authorized (if available). */
+    email?: string;
+};
+/** Persist a session token to ~/.reclaim/session.json (0600). */
+export declare function writeSession(session: CachedSession): void;
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export declare function readSession(): CachedSession | undefined;

package/lib/mcp/credentials/session-cache.js

@@ -0,0 +1,42 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { reclaimHomeDirPath } from "../../paths.js";
+// Separate from credentials.json — sessions expire, credentials don't.
+function sessionCachePath() {
+    return join(reclaimHomeDirPath(), 'session.json');
+}
+/** Persist a session token to ~/.reclaim/session.json (0600). */
+export function writeSession(session) {
+    const dir = reclaimHomeDirPath();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(dir, 0o700);
+    const path = sessionCachePath();
+    writeFileSync(path, JSON.stringify(session, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export function readSession() {
+    const path = sessionCachePath();
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const s = JSON.parse(raw);
+        if (!s.token || !s.expiresAt) {
+            return undefined;
+        }
+        if (new Date(s.expiresAt) <= new Date()) {
+            return undefined; // expired
+        }
+        return s;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/mcp/{tools/credentials → credentials}/status.d.ts

@@ -1,3 +1,3 @@
 import { type ReclaimClient } from '@reclaimprotocol/client';
-import { type RegisteredTool } from '../../server.ts';
+import { type RegisteredTool } from '../server.ts';
 export declare function statusTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/credentials/status.js

@@ -0,0 +1,76 @@
+import { deriveFromPrivateKey, } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
+import { findCached, suggestCredentialForDir } from "./cache.js";
+export function statusTool(client) {
+    return defineTool({
+        name: 'reclaim_status',
+        description: 'Report the live mode (SANDBOX | PRODUCTION | REVOKED) ' +
+            'of a Reclaim app credential. Pass `address` — or omit it ' +
+            'to derive the address from RECLAIM_PRIVATE_KEY, falling ' +
+            'back to the best cached credential for this directory. ' +
+            'Useful to confirm a credential is linked to an org ' +
+            'with billing before running a production flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                address: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'Lowercase ETH address. Defaults to the address ' +
+                        'derived from RECLAIM_PRIVATE_KEY, then the cached ' +
+                        'credential suggested for the current directory.',
+                },
+            },
+        },
+    }, async (args) => {
+        let address = args.address?.toLowerCase();
+        if (!address && process.env.RECLAIM_PRIVATE_KEY) {
+            address = deriveFromPrivateKey(process.env.RECLAIM_PRIVATE_KEY).address;
+        }
+        if (!address) {
+            address = suggestCredentialForDir(findProjectRoot(process.cwd()))
+                ?.credential.address;
+        }
+        if (!address) {
+            throw new Error('No address given, RECLAIM_PRIVATE_KEY is not set, and the ' +
+                'cache is empty. Run issue_credentials or import_credentials ' +
+                'first.');
+        }
+        try {
+            const credResult = (await client.call('GetCredentialByAddress', {
+                params: { address },
+            }));
+            const cred = credResult.data;
+            return {
+                address: cred.address,
+                mode: cred.mode,
+                orgId: cred.orgId,
+                label: cred.label,
+                revokedAt: cred.revokedAt,
+                lastUsedAt: cred.lastUsedAt,
+            };
+        }
+        catch (err) {
+            // Anonymous credentials are not registered server-side, so a
+            // 404 just means "local-only" — which is SANDBOX. Report what
+            // the local cache knows. Other errors propagate. The client
+            // throws a Boom-style ProblemError, so the status lives on
+            // `output.statusCode` / `problem.status`, not `status`.
+            const e = err;
+            const code = e.status ?? e.output?.statusCode ?? e.problem?.status;
+            if (code !== 404) {
+                throw err;
+            }
+            const cached = findCached(address);
+            return {
+                address,
+                mode: 'SANDBOX',
+                ...(cached?.label ? { label: cached.label } : {}),
+                note: 'Local-only credential — not registered with the server. ' +
+                    'It operates in SANDBOX. Link it to an org with billing ' +
+                    '(via link_credential) to reach PRODUCTION.',
+            };
+        }
+    });
+}

package/lib/mcp/instructions.d.ts

@@ -0,0 +1 @@
+export declare const BUILDER_MODE_INSTRUCTIONS: string;

package/lib/mcp/instructions.js

@@ -0,0 +1,11 @@
+/**
+ * MCP server instructions shown to the LLM when running in BUILDER mode
+ * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
+ * (published via the `files` array) so it can be edited as markdown without
+ * touching code. The path resolves identically from `src/mcp` (dev) and
+ * `lib/mcp` (published) — both are two levels below the package root.
+ * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), 'utf8').trim();

package/lib/mcp/register.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Factory entry-point for embedding the reclaim-agent's MCP tools into
+ * a host MCP server. Two consumers:
+ *
+ *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
+ *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
+ *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
+ *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
+ *     agent's 16 tools alongside its auto-generated API tools.
+ *
+ * Shared state — Chrome attach state, capture store, secret store — is
+ * built once per server and threaded through every tool factory.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import { ConfigStore } from '../config/store.ts';
+import { type AttachState } from './tools/attach.ts';
+import { type CaptureStore } from './tools/capture.ts';
+import { type SecretStore } from './tools/propose.ts';
+import { type RegisteredTool } from './server.ts';
+export interface AgentState {
+    attach: {
+        current?: AttachState;
+        config: ConfigStore;
+    };
+    captures: CaptureStore;
+    secrets: SecretStore;
+}
+export declare function buildAgentState(): AgentState;
+/** Build the flat list of `RegisteredTool` entries. Useful when the host
+ *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export declare function buildAgentTools(state: AgentState, client?: ReclaimClient): RegisteredTool[];
+/** Register agent tools on `@reclaimprotocol/client`'s McpServer. Mirrors
+ *  the same shape as builder's auto-generated `registerTools(server, client)`
+ *  in `mcp/api/tools.ts`.
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export declare function registerAgentTools(server: McpServer, state?: AgentState, client?: ReclaimClient): void;

package/lib/mcp/register.js

@@ -0,0 +1,80 @@
+/**
+ * Factory entry-point for embedding the reclaim-agent's MCP tools into
+ * a host MCP server. Two consumers:
+ *
+ *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
+ *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
+ *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
+ *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
+ *     agent's 16 tools alongside its auto-generated API tools.
+ *
+ * Shared state — Chrome attach state, capture store, secret store — is
+ * built once per server and threaded through every tool factory.
+ */
+import { setCryptoImplementation } from '@reclaimprotocol/tls';
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
+import { ConfigStore } from "../config/store.js";
+import { analyzeTool } from "./tools/analyze.js";
+import { attachTool } from "./tools/attach.js";
+import { captureTools } from "./tools/capture.js";
+import { browserTools } from "./tools/eval.js";
+import { findTool } from "./tools/find.js";
+import { proofTool } from "./tools/proof.js";
+import { makeSecretStore, proposeTool, } from "./tools/propose.js";
+import { createVersionFromCaptureTool } from "./tools/publish.js";
+import { replayTool } from "./tools/replay.js";
+import { sessionTools } from "./tools/session.js";
+import { registerToolList } from "./server.js";
+let cryptoInitialized = false;
+/** One-time crypto backend init for @reclaimprotocol/tls. The package
+ *  ships with an empty `crypto = {}` and defers backend choice to the
+ *  caller; without this, the first proof call dies inside the SDK with
+ *  `crypto.randomBytes is not a function`. */
+function ensureCryptoInit() {
+    if (cryptoInitialized) {
+        return;
+    }
+    setCryptoImplementation(webcryptoCrypto);
+    cryptoInitialized = true;
+}
+export function buildAgentState() {
+    return {
+        attach: { config: new ConfigStore() },
+        captures: { sessions: new Map() },
+        secrets: makeSecretStore(),
+    };
+}
+/** Build the flat list of `RegisteredTool` entries. Useful when the host
+ *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export function buildAgentTools(state, client) {
+    ensureCryptoInit();
+    const tools = [];
+    tools.push(attachTool(state.attach));
+    for (const t of captureTools(state.attach, state.captures)) {
+        tools.push(t);
+    }
+    tools.push(findTool(state.captures));
+    for (const t of browserTools(state.attach)) {
+        tools.push(t);
+    }
+    for (const t of sessionTools(state.attach, state.captures, state.secrets)) {
+        tools.push(t);
+    }
+    tools.push(analyzeTool(state.captures));
+    tools.push(proposeTool(state.captures, state.secrets));
+    tools.push(replayTool(state.secrets));
+    tools.push(proofTool(state.secrets));
+    if (client) {
+        tools.push(createVersionFromCaptureTool(client));
+    }
+    return tools;
+}
+/** Register agent tools on `@reclaimprotocol/client`'s McpServer. Mirrors
+ *  the same shape as builder's auto-generated `registerTools(server, client)`
+ *  in `mcp/api/tools.ts`.
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export function registerAgentTools(server, state, client) {
+    const s = state ?? buildAgentState();
+    registerToolList(server, buildAgentTools(s, client));
+}

package/lib/mcp/server.d.ts

@@ -1,9 +1,9 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type JSONSchema } from 'zod-from-json-schema';
+import type { JSONSchema } from 'zod/v4/core';
 export interface ToolDefinition {
     name: string;
     description: string;
-    inputSchema: JSONSchema;
+    inputSchema: JSONSchema.ObjectSchema;
 }
 export interface RegisteredTool {
     definition: ToolDefinition;
@@ -30,9 +30,3 @@ export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (
  * stringification and error catching for tool execution.
  */
 export declare function registerToolList(server: McpServer, tools: RegisteredTool[]): void;
-export declare class ReclaimMcpServer {
-    #private;
-    constructor();
-    register(tool: RegisteredTool): void;
-    listen(): Promise<void>;
-}

package/lib/mcp/server.js

@@ -1,7 +1,4 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { convertJsonSchemaToZod } from 'zod-from-json-schema';
+import { toZod } from "./api/to-zod.js";
 import { remapErrorAsResponse } from "./remap_errors.js";
 /**
  * Define a tool with a single inputSchema (JSON Schema) used as the
@@ -11,7 +8,7 @@ import { remapErrorAsResponse } from "./remap_errors.js";
  * to inbound args cannot drift.
  */
 export function defineTool(definition, handler) {
-    const schema = convertJsonSchemaToZod(definition.inputSchema);
+    const schema = toZod(definition.inputSchema);
     return {
         definition,
         handler: async (raw) => {
@@ -29,7 +26,7 @@ export function registerToolList(server, tools) {
     for (const tool of tools) {
         server.registerTool(tool.definition.name, {
             description: tool.definition.description,
-            inputSchema: convertJsonSchemaToZod(tool.definition.inputSchema),
+            inputSchema: toZod(tool.definition.inputSchema),
         }, async (args) => {
             try {
                 return {
@@ -47,30 +44,3 @@ export function registerToolList(server, tools) {
         });
     }
 }
-export class ReclaimMcpServer {
-    #tools = new Map();
-    #server;
-    constructor() {
-        this.#server = new Server({ name: 'reclaim-agent', version: '0.1.0' }, { capabilities: { tools: {} } });
-        this.#server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            // Double-cast: our `ToolDefinition` carries the same fields as the
-            // SDK's `Tool` but the SDK's type is strict-narrowed and won't
-            // accept ours without going through `unknown`.
-            tools: [...this.#tools.values()].map((t) => t.definition),
-        }));
-        this.#server.setRequestHandler(CallToolRequestSchema, async (req) => {
-            const tool = this.#tools.get(req.params.name);
-            if (!tool) {
-                throw new Error(`unknown tool: ${req.params.name}`);
-            }
-            const result = await tool.handler(req.params.arguments ?? {});
-            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-        });
-    }
-    register(tool) {
-        this.#tools.set(tool.definition.name, tool);
-    }
-    async listen() {
-        await this.#server.connect(new StdioServerTransport());
-    }
-}

package/lib/mcp/start.js

@@ -1,32 +1,35 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { DEFAULT_BASE_URL, ReclaimClient } from '@reclaimprotocol/client';
-import { DEFAULT_OLD_API_URL, ReclaimOldClient } from "../old/client.js";
-import { useOldDevtools } from "../old/flag.js";
+import { ReclaimClient } from '@reclaimprotocol/client';
+import { agentDisabled, apiToken, apiUrl, oldApiUrl, useOldDevtools, } from "../consts.js";
+import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
 import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentTools } from "./tools/agent/build.js";
-import { buildCredentialTools, buildLocalCredentialTools, } from "./tools/credentials/build.js";
-import { readSession } from "./tools/credentials/session-cache.js";
+import { buildAgentTools, buildCredentialTools, buildLocalCredentialTools, buildVerificationTools, readSession, } from "./tools/index.js";
+import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
     const oldMode = useOldDevtools();
-    const server = new McpServer({ name: NAME, version: VERSION }, oldMode ? { instructions: OLD_MODE_INSTRUCTIONS } : undefined);
+    const server = new McpServer({ name: NAME, version: VERSION }, {
+        instructions: oldMode
+            ? OLD_MODE_INSTRUCTIONS
+            : BUILDER_MODE_INSTRUCTIONS,
+    });
     // Agent tools (Chrome CDP capture, provider synthesis, replay, proof) are
     // backend-independent and registered in both modes. Skipped in hosted
     // deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
     // surface.
-    const agentToolsEnabled = process.env.RECLAIM_AGENT_DISABLED !== '1';
+    const agentToolsEnabled = !agentDisabled();
     if (oldMode) {
         // OLD-devtools mode (the default): the legacy backend is still in
         // production while builder is built. All auto-generated builder tools
         // are disabled; a small ReclaimOldClient serves authenticate / publish /
         // get_me_providers instead.
         const oldClient = new ReclaimOldClient({
-            baseUrl: process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL,
+            baseUrl: oldApiUrl(),
             identity: resolveInitialIdentity(),
         });
         registerToolList(server, buildLocalCredentialTools());
@@ -39,9 +42,9 @@ export async function startMcpServer() {
     }
     else {
         const client = new ReclaimClient({
-            baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
+            baseUrl: apiUrl(),
             // Priority: explicit env var → cached session token → unauthenticated
-            token: process.env.RECLAIM_API_TOKEN || readSession()?.token,
+            token: apiToken() || readSession()?.token,
             headers: { 'User-Agent': `${NAME}/${VERSION}` },
         });
         // Tool names must stay disjoint across these three groups: hand-written
@@ -51,6 +54,9 @@ export async function startMcpServer() {
         // collision instead of one tool silently shadowing the other.
         // Register credential tools for ETH credential management.
         registerToolList(server, buildCredentialTools(client));
+        // Higher-level verification orchestrations (e.g. fetch + decrypt result).
+        // Authenticates with RECLAIM_ORG_SECRET, not the session client.
+        registerToolList(server, buildVerificationTools());
         // Add auto-generated tools with snake_case wrappers
         // for every MCP-tagged operation.
         registerTools(server, client);

package/lib/mcp/tools/agent/build.d.ts

@@ -1,12 +1,8 @@
 /**
  * Factory entry-point for embedding the reclaim-agent's MCP tools into
- * a host MCP server. Two consumers:
- *
- *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
- *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
- *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
- *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
- *     agent's 16 tools alongside its auto-generated API tools.
+ * a host MCP server via `registerToolList` (server.ts) on the high-level
+ * `@modelcontextprotocol/sdk` `McpServer`. Folds the agent's tools
+ * alongside the auto-generated API tools.
  *
  * Shared state — Chrome attach state, capture store, secret store — is
  * built once per server and threaded through every tool factory.
@@ -25,8 +21,8 @@ export interface AgentState {
     captures: CaptureStore;
     secrets: SecretStore;
 }
-/** Build the flat list of `RegisteredTool` entries. Useful when the host
- *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+/** Build the flat list of `RegisteredTool` entries, ready for
+ *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
  *  capture/proof tools — old mode supplies its own publish tool. */