@reclaimprotocol/agent 0.1.32 → 0.1.33

package/skill/verification-client-integration.md

@@ -21,19 +21,21 @@ migrating, remove `@reclaimprotocol/js-sdk` and replace its
    error, cancellation, and expiry events. If the app needs encrypted results,
    register its public key with `set_org_keypair`; retain the private key only
    in the backend.
-3. An organization owner can call `issue_org_token`. Its `orgSecret` is shown
-   once. Put it in the app backend's secret configuration as
-   `RECLAIM_ORG_SECRET`; keep it out of frontend bundles, logs, source control,
-   and the final response. Reuse an already configured secret when available;
-   issue a new token when setup needs one.
-4. Prefer plain HTTP from the backend. Create sessions with
-   `POST /verifications/sessions` (`Authorization: Bearer <orgSecret>`), save
-   each returned session ID alongside the app's own user or order, and return
-   only `verificationUrl` to the frontend. The frontend opens that URL and asks
-   its backend for the final status (`GET /verifications/sessions/{sessionId}`);
-   a browser redirect alone is not proof of success. Use
-   `@reclaimprotocol/client` (`ReclaimVerification.create({ orgSecret })`,
-   `sessions.create`) only when the developer asks for it.
+3. Reuse a `RECLAIM_ORG_SECRET` the app already has. Otherwise an organization
+   owner calls `issue_org_token`; its `orgSecret` is shown once. Write it with
+   your file tools into the backend's env file (for example
+   `RECLAIM_ORG_SECRET=rorg_…` in `.env`) and make sure that file is
+   gitignored. Keep it out of frontend bundles, logs, source control, and the
+   final response.
+4. Prefer plain HTTP from the backend (see [Code to write](#code-to-write)).
+   Create sessions with `POST /verifications/sessions`
+   (`Authorization: Bearer $RECLAIM_ORG_SECRET`), save each returned session ID
+   alongside the app's own user or order, and return only `verificationUrl` to
+   the frontend. The frontend opens that URL and asks its backend for the final
+   status (`GET /verifications/sessions/{sessionId}`); a browser redirect alone
+   is not proof of success. Use `@reclaimprotocol/client`
+   (`ReclaimVerification.create({ orgSecret })`, `sessions.create`) only when
+   the developer asks for it.
 5. Add a backend callback endpoint. Persist each delivery idempotently and load
    the expected session ID and org ID from app storage. To verify the result on
    your callback, install `@reclaimprotocol/client` in the backend and call
@@ -51,6 +53,100 @@ consumer backend uses the separate organization token. The SDK's API-only
 entry point, `@reclaimprotocol/client/api`, is available when an application
 needs typed Builder operations without the full verification workflow.
 
+The MCP session tools (`create_verification_session`,
+`get_verification_session`, `list_verification_events`,
+`list_verification_deliveries`, `retry_verification_callback`,
+`create_callback_subscription`, `list_callback_subscriptions`,
+`delete_callback_subscription`, `bind_verification_session_tee_nonce`, and
+`get_verification_result`) call these same production endpoints with the org
+key: pass it as `orgToken`, or let them fall back to the MCP server's
+`RECLAIM_ORG_SECRET`. Use them, or `curl` with the key from `.env`, to test the
+integration end to end.
+
+## Code to write
+
+Use the API base URL the developer's Builder runs at (production:
+`https://build.reclaimprotocol.org`). Every call authenticates with
+`authorization: Bearer $RECLAIM_ORG_SECRET`.
+
+Subscribe a callback once (or use `create_org_callback_subscription`). Session
+creation returns 409 while the org has none, and a result is only delivered to
+subscriptions that include the event the session ends with, so subscribe to all
+five:
+
+```bash
+curl -X POST https://build.reclaimprotocol.org/verifications/callback-subscriptions \
+  -H "authorization: Bearer $RECLAIM_ORG_SECRET" \
+  -H "content-type: application/json" \
+  -d '{
+    "callbackUrl": "https://your.app/reclaim/callback",
+    "events": [
+      "verification_success",
+      "verification_rejected",
+      "verification_error",
+      "verification_cancelled",
+      "session_expired"
+    ]
+  }'
+```
+
+Create a session per claimant, from the backend; store `id` and hand
+`verificationUrl` to the frontend:
+
+```bash
+curl -X POST https://build.reclaimprotocol.org/verifications/sessions \
+  -H "authorization: Bearer $RECLAIM_ORG_SECRET" \
+  -H "content-type: application/json" \
+  -d '{
+    "providers": [
+      {
+        "providerId": "<your-provider-id>"
+      }
+    ],
+    "context": {
+      "userId": "abc"
+    }
+  }'
+```
+
+Receive and verify the result on the callback route. This is the one place the
+client package is needed:
+
+```js
+import { ReclaimVerification } from '@reclaimprotocol/client'
+
+const reclaim = ReclaimVerification.create({
+  orgSecret: process.env.RECLAIM_ORG_SECRET,
+})
+
+app.post('/reclaim/callback', async(req, res) => {
+  const outcome = await reclaim.results.receive(req.body, {
+    reclaimSessionId: sessionId, // the id you stored
+  })
+  if(outcome.kind === 'result') {
+    console.log(outcome.result.payload) // verified
+  }
+
+  res.sendStatus(200)
+})
+```
+
+Check or investigate a session, from the backend (optional, e.g. a status
+endpoint the frontend polls) or by hand with `curl`. All take the org key:
+
+| Route | Use |
+| --- | --- |
+| `GET /verifications/sessions/{sessionId}` | Status and outcome. |
+| `GET /verifications/sessions/{sessionId}/events` | The claimant's event timeline, to see where a flow stopped. |
+| `GET /verifications/sessions/{sessionId}/deliveries` | Callback delivery attempts and their responses. |
+| `GET /verifications/sessions/{sessionId}/result` | Recovery only: a signed result Builder hasn't delivered yet. Builder clears it once the callback succeeds, or after 7 days undelivered (`payload: null`). Verify with `verifyResultFull`. |
+| `POST /verifications/sessions/{sessionId}/retry-callback` | Redeliver an undelivered result (within the 7 days). |
+
+```bash
+curl https://build.reclaimprotocol.org/verifications/sessions/$SESSION_ID \
+  -H "authorization: Bearer $RECLAIM_ORG_SECRET"
+```
+
 ## Create and launch a session
 
 Consumers authenticate with an organization token (`rorg_…`, issued in the
@@ -112,7 +208,8 @@ that public key instead; decrypt it with `@reclaimprotocol/client`'s
 `decryptCallback`/`verifyResult` and the org's eth private key before treating
 it as a result. A session created without `canEncryptResult` never needs this
 step. Troubleshoot a stuck or failed session with `get_verification_session`,
-`list_verification_events`, and `list_org_verification_sessions`.
+`list_verification_events`, `list_verification_deliveries` (all with
+`orgToken`), and `list_org_verification_sessions`.
 
 ## Use the browser extension
 

package/src/mcp/api/operations.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:099a5bcf4fba).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:3e28ff308da3).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -9,7 +9,7 @@ import { toZod } from './to-zod.ts'
 
 export const MCP_TOOLS = {
 	"AddOrgMember": {
-		description: "Invite a member to an organization\n\nOwner only. Invites a user to the organization by email. The invitee does **not** need to be a registered user — an invite is created in either case, and an invite email with an accept link is dispatched. The new row is returned with `status: PENDING`; it flips to `ACTIVE` only when the invitee explicitly accepts via `POST /orgs/{orgId}/invite`. `PERSONAL` organizations reject this call (409).",
+		description: "Invite a member to an organization\n\nOwner only. Invites a user to the organization by email. The invitee does **not** need to be a registered user — an invite is created in either case, and an invite email with an accept link is dispatched. The new row is returned with `status: PENDING`; it flips to `ACTIVE` only when the invitee explicitly accepts via `POST /orgs/{orgId}/invite`.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -50,7 +50,7 @@ export const MCP_TOOLS = {
 						},
 						"role": {
 							"type": "string",
-							"description": "Role a user holds in an organization. `OWNER` can invite, promote, demote, and remove members, and delete the org. `MEMBER` has read/write access to resources owned by the org but cannot manage membership. `PERSONAL` orgs have exactly one `OWNER` and reject all member-mutating operations.",
+							"description": "Role a user holds in an organization. `OWNER` can invite, promote, demote, and remove members, and delete the org. `MEMBER` has read/write access to resources owned by the org but cannot manage membership.",
 							"enum": [
 								"OWNER",
 								"MEMBER"
@@ -425,6 +425,12 @@ export const MCP_TOOLS = {
 							"maxLength": 132
 						}
 					}
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -434,6 +440,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"CancelPublicListingRequest": {
 		description: "Cancel a pending public listing review request\n\nCancels a pending public listing request by moving the version from `in_review` back to `draft`. Only org members can cancel their own review requests. This allows users to withdraw a request before admin review if they change their mind.",
@@ -581,6 +588,12 @@ export const MCP_TOOLS = {
 							}
 						}
 					}
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -590,9 +603,10 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"CreateOrg": {
-		description: "Create an organization\n\nCreates a new `ORG`-kind organization with the caller as its first `OWNER`. The personal org is created automatically at user signup and is not created via this endpoint.",
+		description: "Create an organization\n\nCreates a new `ORG`-kind organization with the caller as its first `OWNER`. Every user gets a default organization at sign-up, and it counts toward their org-creation limit (1 active organization unless Reclaim support raises it). Past the limit this returns `409`; contact support@reclaimprotocol.org to raise the limit or archive an organization.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -611,7 +625,7 @@ export const MCP_TOOLS = {
 				"body": {
 					"type": "object",
 					"additionalProperties": false,
-					"description": "Body for `POST /orgs` — just a name. Every org is created keyless, like auto-provisioned personal orgs; its Ethereum (secp256k1) key pair is published separately via `PUT /orgs/{orgId}/keypair`, which is also where `canEncryptResult` is set. Creation deliberately collects nothing else so it never blocks on generating and safeguarding a private key.",
+					"description": "Body for `POST /orgs` — just a name. Every org is created keyless, like each user's default org; its Ethereum (secp256k1) key pair is published separately via `PUT /orgs/{orgId}/keypair`, which is also where `canEncryptResult` is set. Creation deliberately collects nothing else so it never blocks on generating and safeguarding a private key.",
 					"required": [
 						"name"
 					],
@@ -1580,7 +1594,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"CreateVerificationSession": {
-		description: "Create a verification session\n\nCreates an end-user verification session. Requires an OrgToken and a callback subscription; pass providers, context, and an optional registered verificationClientUrl (omitted: the Portal). Billing refusal returns 402 or 429 with event billing_required and a terminal sessionId.",
+		description: "Create a verification session\n\nCreates an end-user verification session. Requires an OrgToken and a callback subscription; pass providers, context, and an optional registered verificationClientUrl (omitted: the Portal). Send the end user to the returned verificationUrl; that is where they verify. Billing refusal returns 402 or 429 with event billing_required and a terminal sessionId.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -1638,9 +1652,16 @@ export const MCP_TOOLS = {
 						},
 						"verificationClientUrl": {
 							"type": "string",
-							"description": "Optional. Must exactly equal the base URL of a registered verification client (see the `verification_clients` registry / `/admin/verification-clients`). Omit to use the default (`portals`) client. The Builder resolves and stores the registered client UUID, then returns the ready-to-share `verificationUrl` with the session id and `api=2`. A URL that is not a registered client's base is rejected with 400. Consumers append any client-owned redirect parameters after receiving the URL; Builder does not manage them.",
+							"description": "Optional. Must exactly equal the base URL of a registered verification client (see the `verification_clients` registry / `/admin/verification-clients`). Omit to use the default (`portals`) client. The Builder resolves and stores the registered client UUID, then returns the ready-to-share `verificationUrl` with the session id and `api=2`. A URL that is not a registered client's base is rejected with 400. Consumers append any client-owned redirect parameters after receiving the URL; Builder does not manage them. The built-in clients are `{origin}/share/{name}`, listed in the examples.",
 							"maxLength": 2000,
-							"pattern": "^https?://"
+							"pattern": "^https?://",
+							"examples": [
+								"https://build.reclaimprotocol.org/share/portals",
+								"https://build.reclaimprotocol.org/share/verifier-app",
+								"https://build.reclaimprotocol.org/share/reclaim-browser-extension",
+								"https://build.reclaimprotocol.org/share/builder",
+								"https://build.reclaimprotocol.org/share/inapp-sdk"
+							]
 						},
 						"themeId": {
 							"type": "string",
@@ -1755,6 +1776,12 @@ export const MCP_TOOLS = {
 							}
 						}
 					}
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -1764,6 +1791,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"DecideProviderVersionReview": {
 		description: "Record a decision on a provider version review\n\nApproves or rejects a provider version awaiting review. Admin only. Approval promotes the version to the live channel; rejection moves it to the rejected branch with a reason. Use admin_reviews to find versions waiting on a decision.",
@@ -1853,6 +1881,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -1861,6 +1895,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"DeleteOrgCallbackSubscription": {
 		description: "Delete an organization's callback subscription\n\nRemoves a callback subscription. Caller must be an active member of the owning org.",
@@ -2156,15 +2191,22 @@ export const MCP_TOOLS = {
 							"type": "string",
 							"enum": [
 								"claude",
+								"copilot",
 								"cursor",
+								"omp",
 								"opencode",
 								"codex",
+								"antigravity",
 								"others"
 							]
 						},
 						"providerId": {
-							"type": "string",
-							"format": "uuid"
+							"type": "array",
+							"maxItems": 20,
+							"items": {
+								"type": "string",
+								"format": "uuid"
+							}
 						},
 						"client": {
 							"type": "string",
@@ -2571,6 +2613,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -2579,6 +2627,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"ImportDevtoolsProvider": {
 		description: "Import a provider from devtools\n\nImports a public legacy provider into Builder by UUID. Requires human BearerAuth and a target orgId; preserves the provider UUID and is idempotent for seeded providers. Returns 409 if another Builder org owns the UUID.",
@@ -2706,6 +2755,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -2714,6 +2769,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"ListOrgCallbackSubscriptions": {
 		description: "List an organization's callback subscriptions\n\nReturns every callback subscription owned by the organization. Caller must be an active member of the org.",
@@ -2751,7 +2807,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"ListOrgs": {
-		description: "List organizations the caller belongs to\n\nLists the organizations the caller belongs to, personal and shared. Use it first to find an organization id — most other tools take one.",
+		description: "List organizations the caller belongs to\n\nLists the organizations the caller belongs to. Use it first to find an organization id — most other tools take one.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -3018,6 +3074,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -3026,6 +3088,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"ListVerificationEvents": {
 		description: "Get the event log for a session\n\nLists append-only lifecycle events for a session. Requires the owning organization's token. Use after get_verification_session to find the first missing or failed milestone; inspect eventData for failure details.",
@@ -3054,6 +3117,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -3062,6 +3131,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"MakePrivate": {
 		description: "Change a PUBLIC provider back to PRIVATE\n\nChanges a PUBLIC provider's visibility to PRIVATE. Unlike the reverse (PRIVATE → PUBLIC), this does not require review since it restricts rather than expands access. Existing live versions remain but are no longer publicly listed.",
@@ -3251,7 +3321,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"RetryVerificationCallback": {
-		description: "Re-enqueue callback delivery for a session\n\nRe-enqueues delivery of a session's stored result to its callback subscriptions. Use this after `list_verification_deliveries` shows a `failed` or dead-lettered delivery, once the consumer's callback endpoint is reachable again and answers 2xx — it re-attempts every not-yet-delivered callback for the session. Usable by the session creator (authenticated by the consumer's `OrgToken`) to recover from a transient consumer-side outage.",
+		description: "Re-enqueue callback delivery for a session\n\nRe-enqueues delivery of a session's stored result to its callback subscriptions. Use this after `list_verification_deliveries` shows a `failed` or dead-lettered delivery, once the consumer's callback endpoint is reachable again and answers 2xx — it re-attempts every not-yet-delivered callback for the session. Usable by the session creator (authenticated by the consumer's `OrgToken`) to recover from a transient consumer-side outage. A result left undelivered for 7 days is purged and can no longer be retried.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -3277,6 +3347,12 @@ export const MCP_TOOLS = {
 				},
 				"body": {
 					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: 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."
 				}
 			},
 			"required": [
@@ -3285,6 +3361,7 @@ export const MCP_TOOLS = {
 			],
 			"additionalProperties": false
 		}),
+		orgTokenOnly: true,
 	},
 	"RevokeOrgToken": {
 		description: "Revoke one of the organization's API keys\n\nRevokes a single API key by id (leaving the org's other keys intact). The caller must be an active **OWNER** of the organization. The key stops authenticating immediately.",

package/src/mcp/api/tools.ts

@@ -1,9 +1,12 @@
+import { unauthorized } from '@hapi/boom'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
 import type {
 	IOperationArgs,
 	IOperationId
 } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
+import { orgSecret } from '../../consts.ts'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { successResponse } from '../success-response.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
@@ -22,8 +25,29 @@ function toSnakeCase(name: string): string {
 		.toLowerCase()
 }
 
-export function registerTools(server: McpServer, client: ReclaimClient) {
-	for(const [opId, shape] of Object.entries(MCP_TOOLS)) {
+/** The client for a call that presents the organization's API key. */
+export type OrgClientFactory = (orgToken: string) => ReclaimClient
+
+/**
+ * Register a tool per generated operation. Calls go out with the developer's
+ * session token, except operations only an org API key (`rorg_…`) authorizes:
+ * those take an `orgToken` input (else the server's RECLAIM_ORG_SECRET) and go
+ * out through `orgClient` with that key.
+ */
+export function registerTools(
+	server: McpServer,
+	client: ReclaimClient,
+	orgClient: OrgClientFactory = (orgToken) => new ReclaimClient({
+		baseUrl: client.baseUrl,
+		token: orgToken,
+	}),
+) {
+	for(const [opId, tool] of Object.entries(MCP_TOOLS)) {
+		const orgTokenOnly = 'orgTokenOnly' in tool && tool.orgTokenOnly === true
+		const shape = {
+			description: tool.description,
+			inputSchema: tool.inputSchema,
+		}
 		if(!isOperationId(opId)) {
 			throw new Error(
 				`Generated MCP operation is not in the API client: ${opId}`,
@@ -37,13 +61,21 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		server.registerTool(
 			toSnakeCase(opId),
 			shape,
-			async(args: unknown) => {
+			async(input: unknown) => {
 				try {
+					if(!isRecord(input)) {
+						throw new Error(`Invalid generated MCP arguments for ${opId}`)
+					}
+
+					const { orgToken, ...args } = input
 					if(!isOperationArgs(opId, args)) {
 						throw new Error(`Invalid generated MCP arguments for ${opId}`)
 					}
 
-					const result = await client.call(
+					const caller = orgTokenOnly
+						? orgClient(orgTokenFor(toSnakeCase(opId), orgToken))
+						: client
+					const result = await caller.call(
 						opId,
 						args,
 					)
@@ -79,3 +111,23 @@ function isOperationArgs<T extends IOperationId>(
 ): value is IOperationArgs<T> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The org API key a call authenticates with: its `orgToken`, else the
+ *  server's RECLAIM_ORG_SECRET. The session token (the developer's sign-in)
+ *  can't stand in, since these routes accept only an org key. */
+function orgTokenFor(tool: string, orgToken: unknown) {
+	const token = (typeof orgToken === 'string' && orgToken) || orgSecret()
+	assert(
+		token,
+		unauthorized(
+			`${tool} authenticates with the organization's API key. Pass `
+			+ 'orgToken: one from issue_org_token, or the app\'s '
+			+ 'RECLAIM_ORG_SECRET. Or set RECLAIM_ORG_SECRET for the MCP server.',
+		),
+	)
+	return token
+}

package/src/mcp/start.ts

@@ -116,7 +116,12 @@ export async function startMcpServer() {
 
 		// Add auto-generated tools with snake_case wrappers
 		// for every MCP-tagged operation.
-		registerTools(server, client)
+		// Org-key-only operations go out with the call's `orgToken` instead.
+		registerTools(server, client, (orgToken) => new ReclaimClient({
+			baseUrl: apiUrl(),
+			token: orgToken,
+			headers: { 'User-Agent': `${NAME}/${VERSION}` },
+		}))
 
 		if(agentToolsEnabled) {
 			agentState = buildAgentState()

package/src/mcp/tools/verification/result.ts

@@ -17,19 +17,29 @@ const TERMINAL = new Set([
 	'expired',
 ])
 
+/** Events whose delivery is a signed result; the rest are plaintext event
+ *  notifications. Mirrors `verification_result_events()`. */
+const RESULT_EVENTS = new Set([
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+	'verification_cancelled',
+])
+
 /**
  * Resolve the org secret used to authenticate verification reads. Auth is a
- * single per-org bearer secret (`rorg_…`), not an eth signature — read it from
- * `RECLAIM_ORG_SECRET`.
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret(): string {
-	const secret = orgSecret()?.trim()
+function resolveOrgSecret(orgToken?: string): string {
+	const secret = orgToken?.trim() || orgSecret()?.trim()
 	assert(
 		secret,
 		new Error(
-			'RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
-				'the org secret (rorg_…) — issue one from the dashboard ' +
-				'(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.',
+			'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.',
 		),
 	)
 	return secret
@@ -46,12 +56,15 @@ function resolveOrgSecret(): string {
  * Decryption, when needed, happens here.
  */
 export function verificationResultTool(): RegisteredTool {
-	return defineTool<{ reclaimSessionId: string }>(
+	return defineTool<{ reclaimSessionId: string, orgToken?: string }>(
 		{
 			name: 'get_verification_result',
 			description:
-				'Fetches and verifies a terminal Builder result for one session. '
-				+ 'Requires `RECLAIM_ORG_SECRET`; encrypted deliveries also require '
+				'Fetches and verifies a terminal Builder result for one session, '
+				+ '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 '
 				+ '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 '
@@ -65,11 +78,20 @@ export function verificationResultTool(): RegisteredTool {
 						description:
 							'The verification session id from create_verification_session.',
 					},
+					orgToken: {
+						type: 'string',
+						pattern: '^rorg_',
+						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.',
+					},
 				},
 			},
 		},
 		async(args) => {
-			const secret = resolveOrgSecret()
+			const secret = resolveOrgSecret(args.orgToken)
 			// Optional eth decryption key — absent ⇒ plaintext-only.
 			const decryptionKey: DecryptionKey | undefined =
 				await resolveDecryptionKey()
@@ -91,14 +113,34 @@ export function verificationResultTool(): RegisteredTool {
 			const resultRes = await reclaim.api('GetVerificationResult', {
 				params: { sessionId: args.reclaimSessionId },
 			})
-			const { items } = resultRes.data
+			const signed = resultRes.data.items
+				.filter((item) => RESULT_EVENTS.has(item.event))
+			if(!signed.length) {
+				return {
+					reclaimSessionId: args.reclaimSessionId,
+					status,
+					ready: false,
+					note: 'Session is terminal but no result is stored: none submitted '
+						+ 'yet, or no callback subscription covers its ending event.',
+				}
+			}
 
+			// Builder keeps a result (which can carry proofs) only until its
+			// callback is delivered, or 7 days undelivered.
+			const items = signed.flatMap((item) => (
+				item.payload === null ? [] : [{ ...item, payload: item.payload }]
+			))
 			if(!items.length) {
 				return {
 					reclaimSessionId: args.reclaimSessionId,
 					status,
 					ready: false,
-					note: 'Session is terminal but no result has been submitted yet.',
+					delivered: signed.some((item) => (
+						item.deliveryStatus === 'delivered'
+					)),
+					note: 'Builder no longer holds this result: it was delivered to '
+						+ 'the callback (read it there), or went undelivered for 7 days. '
+						+ 'See list_verification_deliveries.',
 				}
 			}