@neus/mcp-server 1.0.0

package/server.js

@@ -0,0 +1,4420 @@
+#!/usr/bin/env node
+/**
+ * NEUS MCP Server
+ * 
+ * Model Context Protocol server for NEUS verification and proof workflows.
+ * Supports both stdio (local) and HTTP (production) transports.
+ * Implements MCP Elicitation for human-in-the-loop agent workflows.
+ * 
+ * @license Apache-2.0
+ */
+
+import { initTelemetry } from '../src/utils/telemetry.js';
+initTelemetry();
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID, scryptSync, timingSafeEqual } from 'node:crypto';
+import { privateKeyToAccount } from 'viem/accounts';
+import { z } from 'zod';
+import vm from 'node:vm';
+import { buildMcpConfig } from '../src/config/mcpConfig.js';
+
+const mcp = buildMcpConfig(process.env);
+
+const zeusMcpFileUrl = import.meta.url;
+const requireFromMcp = createRequire(fileURLToPath(zeusMcpFileUrl));
+const { buildZeusProofIndexTags, proofTagsMatchAllPrefixes } = requireFromMcp(
+  fileURLToPath(new URL('../src/utils/zeusProofIndexTags.cjs', import.meta.url)),
+);
+/** @type {Set<string>} */
+const ZEUS_SANDBOX_REQUIRE_ALLOW = new Set(['nodemailer', 'https', 'http', 'url', 'querystring']);
+
+/**
+ * @param {string} id
+ * @returns {unknown}
+ */
+function requireInZeusSandbox(id) {
+  const mod = String(id || '').replace(/\\/g, '/');
+  if (!mod) {
+    throw new TypeError('require: module id is required');
+  }
+  if (mod.startsWith('node:') || (mod[0] !== '.' && mod[0] !== '/')) {
+    const root = mod.split('/')[0] || mod;
+    if (ZEUS_SANDBOX_REQUIRE_ALLOW.has(root) || mod === 'nodemailer' || mod.startsWith('nodemailer/')) {
+      return requireFromMcp(mod);
+    }
+  }
+  throw new Error(
+    `[Zeus sandbox] require('${id}') is not allowed. Allowed: ${[...ZEUS_SANDBOX_REQUIRE_ALLOW].join(', ')}.`
+  );
+}
+
+/**
+ * @returns {Record<string, string|undefined>}
+ */
+function zeusSandboxGmailProcessEnv() {
+  return {
+    GMAIL_USER: process.env.GMAIL_USER,
+    GMAIL_APP_PASSWORD: process.env.GMAIL_APP_PASSWORD
+  };
+}
+
+/**
+ * McpServer validates tool arguments with Zod only; plain JSON Schema objects are not parsed correctly.
+ * TOOLS[].inputSchema stays the JSON Schema contract for /.well-known and docs.
+ * TOOL_ZOD_INPUT mirrors those shapes so tools/list exposes properties to MCP clients.
+ */
+
+const NEUS_API_URL = mcp.neusApiUrl;
+const NEUS_MCP_INFERENCE_BASE_URL = mcp.mcpInferenceBaseUrl;
+const NEUS_MCP_INFERENCE_KEY = mcp.mcpInferenceKey;
+const NEUS_MCP_INFERENCE_MODEL = mcp.mcpInferenceModel;
+/** In-flight execute_agent_command jobs (per MCP process) for stop_agent_processing */
+const agentInferenceJobs = new Map();
+const MCP_APP_ID = mcp.mcpAppId;
+// Process default for NEUS API calls (stdio / self-hosted). Not the MCP HTTP gateway secret.
+const NEUS_AUTH_TOKEN = mcp.neusAuthToken;
+const MCP_PUBLIC_URL = mcp.mcpPublicUrl;
+const API_TIMEOUT_MS = 5 * 60 * 1000;
+const API_MAX_RETRIES = mcp.apiMaxRetries;
+const API_RETRY_BASE_MS = mcp.apiRetryBaseMs;
+const SHUTDOWN_TIMEOUT_MS = mcp.shutdownTimeoutMs;
+
+/** MCP initialize protocol version wire string (distinct from MCP installer manifest versioning). */
+const MCP_PROTOCOL_VERSION = mcp.mcpProtocolVersion;
+
+function log(level, event, details = {}) {
+  const payload = {
+    ts: new Date().toISOString(),
+    level,
+    event,
+    ...details
+  };
+  console.error(JSON.stringify(payload));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+const ENCRYPT_TAG_OPEN = '<encrypt>';
+const ENCRYPT_TAG_CLOSE = '</encrypt>';
+const ENCRYPT_REGEX = /<encrypt>([\s\S]*?)<\/encrypt>/g;
+const SENSITIVE_KEY_RE = /(api[-_ ]?key|secret|password|passkey|private[-_ ]?key|token|authorization|client[-_ ]?secret|app[-_ ]?secret)/i;
+const SENSITIVE_VALUE_RE = /(npk_[a-zA-Z0-9_-]{8,}|sk-[a-zA-Z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9._-]{10,}\.[A-Za-z0-9._-]{10,})/;
+let runtimeCryptoKey = null;
+let loggedEphemeralCryptoWarning = false;
+
+function getRuntimeCryptoKey() {
+  if (runtimeCryptoKey) return runtimeCryptoKey;
+  if (mcp.cryptoSecret) {
+    runtimeCryptoKey = scryptSync(mcp.cryptoSecret, 'neus-mcp-v1', 32);
+    return runtimeCryptoKey;
+  }
+  runtimeCryptoKey = randomBytes(32);
+  if (!loggedEphemeralCryptoWarning) {
+    loggedEphemeralCryptoWarning = true;
+    log('warn', 'crypto_ephemeral_key_in_use', {
+      message:
+        'NEUS_MCP_CRYPTO_SECRET is not set. Generated an ephemeral encryption key for this process; encrypted text cannot be decrypted after restart.'
+    });
+  }
+  return runtimeCryptoKey;
+}
+
+function wrapEncryptedPayload(payload) {
+  return `${ENCRYPT_TAG_OPEN}${payload}${ENCRYPT_TAG_CLOSE}`;
+}
+
+function isWrappedEncrypted(value) {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  return trimmed.startsWith(ENCRYPT_TAG_OPEN) && trimmed.endsWith(ENCRYPT_TAG_CLOSE);
+}
+
+function encryptPlaintext(plain) {
+  const text = String(plain ?? '');
+  const key = getRuntimeCryptoKey();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return JSON.stringify({
+    v: 1,
+    alg: 'aes-256-gcm',
+    iv: iv.toString('base64'),
+    tag: tag.toString('base64'),
+    ct: ciphertext.toString('base64')
+  });
+}
+
+function decryptPayload(payload) {
+  const key = getRuntimeCryptoKey();
+  const parsed = typeof payload === 'string' ? JSON.parse(payload) : payload;
+  if (!parsed || Number(parsed.v) !== 1 || parsed.alg !== 'aes-256-gcm') {
+    throw new Error('Unsupported encrypted payload format');
+  }
+  const iv = Buffer.from(String(parsed.iv || ''), 'base64');
+  const tag = Buffer.from(String(parsed.tag || ''), 'base64');
+  const ct = Buffer.from(String(parsed.ct || ''), 'base64');
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return plain.toString('utf8');
+}
+
+function decryptEmbeddedTags(input) {
+  if (typeof input !== 'string') return input;
+  if (!input.includes(ENCRYPT_TAG_OPEN)) return input;
+  return input.replace(ENCRYPT_REGEX, (_m, payload) => {
+    try {
+      return decryptPayload(String(payload || '').trim());
+    } catch {
+      return _m;
+    }
+  });
+}
+
+function looksSensitiveValue(value) {
+  if (typeof value !== 'string') return false;
+  const text = value.trim();
+  if (!text) return false;
+  if (isWrappedEncrypted(text)) return false;
+  if (SENSITIVE_VALUE_RE.test(text)) return true;
+  if (text.length >= 24 && !/\s/.test(text) && /[A-Za-z]/.test(text) && /\d/.test(text)) return true;
+  return false;
+}
+
+function shouldEncryptKey(key) {
+  return typeof key === 'string' && SENSITIVE_KEY_RE.test(key);
+}
+
+function decryptArgsDeep(value) {
+  if (typeof value === 'string') return decryptEmbeddedTags(value);
+  if (Array.isArray(value)) return value.map((item) => decryptArgsDeep(item));
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) out[k] = decryptArgsDeep(v);
+  return out;
+}
+
+/**
+ * neus_agent_create returns agent.generatedWallet with raw 0x address and private key. Both match
+ * looksSensitiveValue (long hex) or SENSITIVE_KEY_RE (privateKey) and would otherwise be wrapped
+ * in <encrypt>, breaking JSON consumers and local E2E.
+ */
+function isExemptedAgentGeneratedWalletString(path, keyHint, value) {
+  if (typeof value !== 'string' || isWrappedEncrypted(value)) return false;
+  const p = String(path);
+  if (!p.includes('generatedWallet')) return false;
+  const t = value.trim();
+  if (p.endsWith('.address') && /^0x[0-9a-fA-F]{40}$/.test(t)) return true;
+  if ((keyHint === 'privateKey' || p.split('.').pop() === 'privateKey') && /^0x[0-9a-fA-F]{64}$/.test(t)) {
+    return true;
+  }
+  return false;
+}
+
+function isPublicHostedVerifyOrCheckoutUrlField(keyHint, value) {
+  if (keyHint !== 'hostedVerifyUrl' && keyHint !== 'hostedCheckoutUrl') return false;
+  if (typeof value !== 'string' || isWrappedEncrypted(value)) return false;
+  const t = value.trim();
+  return t.startsWith('https://') || t.startsWith('http://');
+}
+
+/** Public EVM addresses in tool JSON (not secrets)  —  would match looksSensitiveValue otherwise. */
+function isExemptedPublicEvmAddressField(keyHint, value) {
+  if (typeof value !== 'string' || isWrappedEncrypted(value)) return false;
+  if (keyHint !== 'principal' && keyHint !== 'signer' && keyHint !== 'agentWallet' && keyHint !== 'controllerWallet' && keyHint !== 'walletAddress' && keyHint !== 'address') {
+    return false;
+  }
+  return /^0x[0-9a-fA-F]{40}$/.test(value.trim());
+}
+
+function encryptSensitiveDeep(value, path = '') {
+  if (typeof value === 'string') {
+    const keyHint = path.split('.').pop() || '';
+    if (isExemptedAgentGeneratedWalletString(path, keyHint, value)) {
+      return value;
+    }
+    if (isPublicHostedVerifyOrCheckoutUrlField(keyHint, value)) {
+      return value;
+    }
+    if (isExemptedPublicEvmAddressField(keyHint, value)) {
+      return value;
+    }
+    if ((shouldEncryptKey(keyHint) || looksSensitiveValue(value)) && !isWrappedEncrypted(value)) {
+      return wrapEncryptedPayload(encryptPlaintext(value));
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item) => encryptSensitiveDeep(item, path));
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    const nextPath = path ? `${path}.${k}` : k;
+    if (typeof v === 'string' && shouldEncryptKey(k) && !isWrappedEncrypted(v)) {
+      if (isExemptedAgentGeneratedWalletString(nextPath, k, v)) {
+        out[k] = v;
+        continue;
+      }
+      out[k] = wrapEncryptedPayload(encryptPlaintext(v));
+      continue;
+    }
+    out[k] = encryptSensitiveDeep(v, nextPath);
+  }
+  return out;
+}
+
+function shouldRetryStatus(status) {
+  return Number.isFinite(Number(status)) && Number(status) >= 500;
+}
+
+function shouldRetryError(err) {
+  const code = String(err?.code || '').toUpperCase();
+  return code === 'ECONNRESET' || code === 'ETIMEDOUT' || code === 'ENOTFOUND' || code === 'EAI_AGAIN';
+}
+
+/**
+ * Normalize agent skill refs for agent-identity / agent-delegation payloads (aligns with verifiers).
+ * @param {unknown} skills
+ * @returns {object[]|null}
+ */
+function normalizeMcpAgentSkills(skills) {
+  if (!Array.isArray(skills)) return null;
+  const cleaned = [];
+  const kinds = new Set(['native', 'integration', 'plugin', 'mcp', 'toolkit']);
+  for (const skill of skills.slice(0, 48)) {
+    if (!skill || typeof skill !== 'object') continue;
+    const id = typeof skill.id === 'string' ? skill.id.trim() : '';
+    if (!id || id.length > 64) continue;
+    cleaned.push({
+      id,
+      label: typeof skill.label === 'string' ? skill.label.trim().slice(0, 64) : id,
+      ...(typeof skill.version === 'string' ? { version: skill.version.trim().slice(0, 32) } : {}),
+      ...(typeof skill.provider === 'string' ? { provider: skill.provider.trim().slice(0, 64) } : {}),
+      ...(kinds.has(skill.kind) ? { kind: skill.kind } : {}),
+      ...(typeof skill.configId === 'string' ? { configId: skill.configId.trim().slice(0, 128) } : {}),
+      ...(typeof skill.enabled === 'boolean' ? { enabled: skill.enabled } : {}),
+    });
+  }
+  return cleaned.length > 0 ? cleaned : null;
+}
+
+/**
+ * @param {unknown} services
+ * @returns {object[]|null}
+ */
+function normalizeMcpAgentServices(services) {
+  if (!Array.isArray(services)) return null;
+  const cleaned = [];
+  for (const s of services.slice(0, 16)) {
+    if (!s || typeof s !== 'object') continue;
+    const name = typeof s.name === 'string' ? s.name.trim().slice(0, 64) : '';
+    const endpoint = typeof s.endpoint === 'string' ? s.endpoint.trim().slice(0, 256) : '';
+    const version = typeof s.version === 'string' ? s.version.trim().slice(0, 32) : '';
+    if (!name || !endpoint) continue;
+    try {
+      const parsed = new URL(endpoint);
+      if (!parsed.protocol || !parsed.hostname) continue;
+    } catch {
+      continue;
+    }
+    cleaned.push({
+      name,
+      endpoint,
+      ...(version ? { version } : {}),
+    });
+  }
+  return cleaned.length > 0 ? cleaned : null;
+}
+
+// ============================================================================
+// TOOL DEFINITIONS (single source of truth for MCP tool names and inputSchema)
+// ============================================================================
+
+const TOOLS = [
+  {
+    name: 'neus_context',
+    description:
+      'NEUS MCP session home: product summary, setup, access-key mode, verifier summaries, reuse-first workflow, tools, and safety rules. Always call first.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'neus_verifiers_catalog',
+    description:
+      'Full verifier directory with JSON schemas. Use after neus_context when payloads need exact fields beyond the summary.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'neus_proofs_check',
+    description: 'Checks whether existing proofs satisfy verifier IDs. Eligibility only; never creates proofs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        wallet: { type: 'string', description: 'Identifier to check: wallet (0x.../base58) or DID (did:pkh:...)' },
+        verifiers: { type: 'array', items: { type: 'string' }, description: 'Verifier IDs to check (e.g., ["ownership-basic", "proof-of-human"]). Get IDs from neus_verifiers_catalog.' },
+        requireAll: { type: 'boolean', description: 'Require all verifiers (default: false = any)' },
+        minCount: { type: 'number', description: 'Minimum number of matching proofs (default: 1)' }
+      },
+      required: ['wallet', 'verifiers']
+    }
+  },
+  {
+    name: 'neus_verify',
+    description:
+      'Creates or continues verification only when Profile access, wallet, and signing already satisfy NEUS for this verifier. Check existing receipts first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        walletAddress: { type: 'string', description: 'Identifier to verify: wallet (EVM/Solana) or DID (did:pkh:...)' },
+        verifierIds: { type: 'array', items: { type: 'string' }, description: 'Verifier IDs to run (e.g., ["ownership-basic", "proof-of-human"])' },
+        data: {
+          type: 'object',
+          description:
+            'Verifier payload from neus_verifiers_catalog. Omit or send {} when requiredFields are empty.'
+        },
+        chain: { type: 'string', description: 'Network identifier — omit when NEUS infers it from the address format.' },
+        signature: {
+          type: 'string',
+          description: 'Approver signature emitted by NEUS on the preparation response — omit on the preparation call.'
+        },
+        signedTimestamp: { type: 'number', description: 'Unix timestamp in ms (auto-generated if missing)' },
+        options: {
+          type: 'object',
+          description: 'Optional verification options',
+          properties: {
+            returnUrl: { type: 'string', description: 'Partner return URL for post-verification redirect (hosted flow)' }
+          }
+        }
+      },
+      required: ['walletAddress', 'verifierIds']
+    }
+  },
+  {
+    name: 'neus_verify_or_guide',
+    description:
+      'Fallback orchestration after reuse checks: use only when proof, profile, payment, provider, wallet, or delegation setup is missing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        walletAddress: { type: 'string', description: 'Identifier to verify: wallet (EVM/Solana) or DID (did:pkh:...)' },
+        verifierIds: { type: 'array', items: { type: 'string' }, description: 'Verifier IDs to check/create. Get IDs from neus_verifiers_catalog.' },
+        data: { type: 'object', description: 'Verifier-specific data payload (used only if verification needed)' },
+        requireAll: { type: 'boolean', description: 'Require all verifiers (default: false = any)' },
+        chain: { type: 'string', description: 'Optional network hint — omit when NEUS can infer it from the wallet format.' },
+        options: { type: 'object', description: 'Optional verification options' }
+      },
+      required: ['walletAddress', 'verifierIds']
+    }
+  },
+  {
+    name: 'neus_proofs_get',
+    description:
+      'Reads proof records, tags, delegated agent reads, Profile summary fields, and live proof state. qHashes in the response are authoritative.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string', description: 'Wallet address (EVM 0x... or Solana base58) or DID (did:pkh:...)' },
+        limit: { type: 'number', description: 'Max proof records to return (default: 50, max: 100)' },
+        offset: { type: 'number', description: 'Pagination offset (default: 0)' },
+        tags: {
+          type: 'string',
+          description:
+            'Optional comma-separated tag filter (use values you have seen on prior neus_proofs_get results).'
+        },
+        scope: {
+          type: 'string',
+          description:
+            'Optional preset when tags omitted: memory | research | rules | instruction | tools | receipts.'
+        },
+        agentWallet: {
+          type: 'string',
+          description:
+            'Optional agent wallet address for delegated proof reads — only when delegation is enabled for your account.'
+        },
+        q: { type: 'string', description: 'Full-text search (by-wallet ?q= when supported).' },
+        searchQuery: { type: 'string', description: 'Alias of q.' },
+        verifierId: {
+          type: 'string',
+          description:
+            'Optional single verifier id filter (passed to GET /proofs/by-wallet ?verifierId=). Prefer this for targeted reads instead of fetching a large page and filtering client-side.'
+        },
+        tagPrefix: { type: 'string', description: 'After fetch, keep only proofs with a tag starting with this prefix.' },
+        tagContains: { type: 'string', description: 'After fetch, keep only proofs with any tag containing this substring.' },
+        tagPrefixesAll: {
+          type: 'string',
+          description:
+            'After fetch, keep proofs where every comma-separated prefix matches the start of some tag (AND), e.g. memory:john_,topic:acme.'
+        }
+      },
+      required: ['identifier']
+    }
+  },
+  {
+    name: 'neus_me',
+    description:
+      'Returns the signed-in NEUS Profile when a personal access key from Profile → Account is configured on this MCP session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: {
+          type: 'string',
+          description: 'Optional wallet or DID. Omit to infer from the personal access key stored on this MCP session.'
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'neus_agent_link',
+    description:
+      'Readiness check for an agent wallet: returns linked when agent-identity and agent-delegation proofs exist; otherwise link_required with hostedVerifyUrl.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agentWallet: { type: 'string', description: 'Agent wallet address (required)' },
+        principal: {
+          type: 'string',
+          description: 'Optional approving wallet/DID — omit once neus_me already clarified the approving account.'
+        }
+      },
+      required: ['agentWallet']
+    }
+  },
+  {
+    name: 'neus_agent_create',
+    description:
+      'Prepares agent-identity and agent-delegation payloads (signatures and/or hostedVerifyUrl). Does not finalize receipts; confirm with neus_agent_link after signing. Skills/services fields are metadata only, not secrets.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agentWallet: { type: 'string', description: 'Agent wallet, or the literal "generate" for an auto-generated key (integrator-only  —  store the private key securely).' },
+        controllerWallet: { type: 'string', description: 'Optional approving account wallet when you must supply it explicitly (must sign the access-approval step). Not the agent wallet.' },
+        agentId: { type: 'string', description: 'Human-readable agent identifier (e.g., "my-ai-assistant"). Max 128 chars.' },
+        agentLabel: { type: 'string', description: 'Display name for the agent (optional, defaults to agentId).' },
+        agentType: { type: 'string', description: 'Type of agent: "ai", "bot", "service", "automation", or "agent" (default: "ai").' },
+        description: { type: 'string', description: 'Agent description (optional, max 500 chars).' },
+        capabilities: { type: 'array', items: { type: 'string' }, description: 'Capability flags: "wallet", "signing", "spending", "publishing", "search", "browser", "mcp", "webhooks", "receipts", "proofs", "delegation".' },
+        permissions: { type: 'array', items: { type: 'string' }, description: 'Permissions to grant agent (e.g., ["read-proofs", "write-proofs", "invoke-services"]).' },
+        scope: { type: 'string', description: 'Delegation scope (default: "global"). Use "payments:x402" for payment agents.' },
+        expiresAt: { type: 'number', description: 'Unix timestamp in ms when delegation expires (optional, 0 = never).' },
+        maxSpend: {
+          type: 'string',
+          description:
+            'Optional spend cap: whole-number string in token base units (1 — 78 digits, no decimal point). For USDC (typical x402 flows), use six decimal places — see SDK toAgentDelegationMaxSpend.',
+        },
+        chain: { type: 'string', description: 'CAIP-2 chain identifier. Auto-detected from wallet format if omitted.' },
+        preset: { type: 'string', description: 'Quick preset: "full-access" (all capabilities), "payments" (x402 scope), "readonly" (read-proofs only), "automation" (browser+mcp).' },
+        instructions: {
+          type: 'string',
+          description:
+            'Optional operating instructions for agent-identity (max 16000 chars). Included in the signed identity payload: system or developer prompt, tool-use policy, and safety/PII rules — portable with the proof.',
+        },
+        skills: {
+          type: 'array',
+          description:
+            'Optional AgentSkillRef[] for agent-identity (id, label, version, provider, kind, configId, enabled). configId is an optional opaque integration reference (not a secret, not an OAuth token, not credential material).',
+          items: { type: 'object', additionalProperties: true },
+        },
+        services: {
+          type: 'array',
+          description: 'Optional services for agent-identity: { name, endpoint (URL), version? }.',
+          items: { type: 'object', additionalProperties: true },
+        },
+        delegationInstructions: {
+          type: 'string',
+          description: 'Optional controller policy text for agent-delegation (max 16000 chars), signed by controllerWallet.',
+        },
+        delegationSkills: {
+          type: 'array',
+          description:
+            'Optional AgentSkillRef[] for agent-delegation. configId is an optional opaque integration reference (not a secret, not an OAuth token, not credential material).',
+          items: { type: 'object', additionalProperties: true },
+        },
+      },
+      required: ['agentId']
+    }
+  },
+  {
+    name: 'zeus_url_fetch',
+    description:
+      'Fetch public http(s) HTML/text quickly for Zeus. Blocks local/private/metadata hosts and truncates body by maxChars.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'Public http(s) URL to fetch.' },
+        maxChars: { type: 'number', description: 'Max response chars (default 120000, max 400000).' }
+      },
+      required: ['url']
+    }
+  },
+  {
+    name: 'zeus_execute_javascript',
+    description:
+      'Execute JavaScript in a Zeus sandbox (async/await). Use return or set `result`. `require` only allows `nodemailer` (Gmail: use `process.env.GMAIL_USER` / `process.env.GMAIL_APP_PASSWORD` on the MCP process — do not put secrets in proof text). For NEUS API calls from a hosted BFF, use the hub `zeus_execute_javascript` path which provides `zeus.get` / `zeus.post`. Response includes `logs` from `console` in the script.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        script: { type: 'string', description: 'JavaScript source. Set result = ... or return an expression.' },
+        input: { type: 'object', description: 'JSON input object available as input.' },
+        timeoutMs: { type: 'number', description: 'Timeout in ms (default 4000, max 15000).' }
+      },
+      required: ['script']
+    }
+  },
+  {
+    name: 'execute_javascript_code',
+    description:
+      'Same behavior as zeus_execute_javascript (Zeus Node sandbox; response includes `logs` from the script — s console). Exposed for agents that need the dedicated name; profile Zeus chat also echoes `logs` to the user — s browser console when this tool is used from the BFF agent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        script: { type: 'string', description: 'JavaScript source. Set result = ... or return an expression.' },
+        input: { type: 'object', description: 'JSON input object available as input.' },
+        timeoutMs: { type: 'number', description: 'Timeout in ms (default 4000, max 15000).' }
+      },
+      required: ['script']
+    }
+  },
+  {
+    name: 'zeus_skill_tools_list',
+    description:
+      'Fast list of proof-backed Zeus tools/skills from wallet inventory (tags tool,skill,agent:tool,agent:skill).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string', description: 'Wallet/DID. Defaults to Bearer profile wallet when available.' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'zeus_skill_tool_execute',
+    description:
+      'Execute JavaScript stored in a tool/skill proof. Expected content: markdown summary, separator line -----, then JavaScript.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        qHash: { type: 'string' },
+        input: { type: 'object' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['qHash']
+    }
+  },
+  {
+    name: 'zeus_session_receipt_create',
+    description:
+      'Create a private NEUS memory proof tagged receipt:chat (Zeus turn/session audit). Not shown on the trust graph; still readable by qHash. Requires Bearer profile wallet or explicit walletAddress.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        walletAddress: { type: 'string' },
+        title: { type: 'string' },
+        content: { type: 'string' },
+        tags: { type: 'array', items: { type: 'string' } },
+        asPrivate: { type: 'boolean', description: 'Ignored; receipts are always private.' }
+      },
+      required: ['content']
+    }
+  },
+  {
+    name: 'zeus_session_receipt_append',
+    description:
+      'Append a response/update to an existing receipt by creating a superseding private proof tagged receipt:chat and supersedes:<qHash>.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        qHash: { type: 'string' },
+        walletAddress: { type: 'string' },
+        appendContent: { type: 'string' },
+        title: { type: 'string' },
+        asPrivate: { type: 'boolean', description: 'Ignored; receipts are always private.' }
+      },
+      required: ['qHash', 'appendContent']
+    }
+  },
+  {
+    name: 'list_tools',
+    description:
+      'Dictionary (title -> qHash) and items list for proofs in the connected wallet tagged tool or skill (incl. agent:tool, agent:skill). Optional q / tagPrefix / tagContains filters (same as list_memories). Requires identifier or Bearer profile wallet.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string' },
+        searchQuery: { type: 'string' },
+        tagPrefix: { type: 'string' },
+        tagContains: { type: 'string' },
+        tagPrefixesAll: {
+          type: 'string',
+          description: 'AND filter: comma-separated tag prefixes; each must match start of some proof tag.'
+        }
+      }
+    }
+  },
+  {
+    name: 'list_all_available_tools',
+    description:
+      'Return an array containing every callable MCP function name exposed by this protocol/mcp server.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'list_memories',
+    description:
+      'Dictionary and items for proofs tagged memory (includes facet tags like memory:users_name, topic:*, domain:*, zeus:index:v3). Filter with tagPrefix / tagContains / tagPrefixesAll (AND on prefixes), or pass q/searchQuery for full-text when the API supports it. Requires identifier or Bearer profile wallet.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string', description: 'Full-text search forwarded to by-wallet ?q= when supported.' },
+        searchQuery: { type: 'string', description: 'Alias of q.' },
+        tagPrefix: { type: 'string', description: 'Only proofs with a tag starting with this (e.g. memory:john_)' },
+        tagContains: { type: 'string', description: 'Only proofs with any tag containing this substring.' },
+        tagPrefixesAll: {
+          type: 'string',
+          description: 'Comma-separated prefixes; every prefix must match the start of some tag on the proof.'
+        }
+      }
+    }
+  },
+  {
+    name: 'list_research',
+    description:
+      'Dictionary and items for proofs tagged research. Same optional q / tagPrefix / tagContains / tagPrefixesAll filters as list_memories.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string' },
+        searchQuery: { type: 'string' },
+        tagPrefix: { type: 'string' },
+        tagContains: { type: 'string' },
+        tagPrefixesAll: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'list_instructions',
+    description:
+      'Dictionary and items for proofs tagged instruction or instructions. Optional q / tagPrefix / tagContains / tagPrefixesAll filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string' },
+        searchQuery: { type: 'string' },
+        tagPrefix: { type: 'string' },
+        tagContains: { type: 'string' },
+        tagPrefixesAll: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'list_rules',
+    description:
+      'Dictionary and items for proofs tagged rule or rules. Optional q / tagPrefix / tagContains / tagPrefixesAll filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string' },
+        searchQuery: { type: 'string' },
+        tagPrefix: { type: 'string' },
+        tagContains: { type: 'string' },
+        tagPrefixesAll: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'list_mcps',
+    description:
+      'Dictionary and items for proofs tagged mcp (MCP connection / integration records). Optional q / tagPrefix / tagContains / tagPrefixesAll filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        offset: { type: 'number' },
+        agentWallet: { type: 'string' },
+        q: { type: 'string' },
+        searchQuery: { type: 'string' },
+        tagPrefix: { type: 'string' },
+        tagContains: { type: 'string' },
+        tagPrefixesAll: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'get_tool',
+    description: 'Fetch a proof by qHash; must be tagged as a tool (or agent:tool).',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'get_skill',
+    description: 'Fetch a proof by qHash; must be tagged as a skill (or agent:skill).',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'get_memory',
+    description: 'Fetch a proof by qHash; must be tagged memory.',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'get_instruction',
+    description: 'Fetch a proof by qHash; must be tagged instruction or instructions.',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'get_rule',
+    description: 'Fetch a proof by qHash; must be tagged rule or rules.',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'get_research',
+    description: 'Fetch a proof by qHash; must be tagged research.',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, id: { type: 'string' } },
+      required: []
+    }
+  },
+  {
+    name: 'append_Content_to_memory',
+    description:
+      'Append text to an existing memory-tagged proof by creating a superseding ownership-basic proof (supersedes:qHash). Regenerates dense Zeus index tags (memory:*, topic:*, domain:*, zeus:index:v3); optional indexFacetKeys adds explicit memory:slug facets.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        qHash: { type: 'string' },
+        appendContent: { type: 'string' },
+        content: { type: 'string' },
+        walletAddress: { type: 'string' },
+        asPrivate: { type: 'boolean' },
+        indexFacetKeys: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional facet keys merged like zeus_memory_create (memory:slug or raw tag strings).'
+        }
+      },
+      required: ['qHash']
+    }
+  },
+  {
+    name: 'delete_revoke_memory',
+    description: 'Revoke a memory-tagged proof via POST /proofs/revoke-self (Bearer/session wallet).',
+    inputSchema: {
+      type: 'object',
+      properties: { qHash: { type: 'string' }, walletAddress: { type: 'string' } },
+      required: ['qHash']
+    }
+  },
+  {
+    name: 'list_agents',
+    description:
+      'List agent-identity and agent-delegation derived entries for the wallet (config-style fields: capabilities, skills, permissions, scope, etc.).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string' },
+        limit: { type: 'number' },
+        agentWallet: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'execute_agent_command',
+    description:
+      'Run a one-shot non-streaming OpenAI-style chat for a delegate prompt. Requires NEUS_MCP_INFERENCE_API_KEY or OPENROUTER_API_KEY on the MCP host. Returns requestId for stop_agent_processing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string' },
+        agentWallet: { type: 'string' },
+        agentId: { type: 'string' },
+        model: { type: 'string' },
+        systemPrompt: { type: 'string' },
+        temperature: { type: 'number' }
+      },
+      required: ['prompt']
+    }
+  },
+  {
+    name: 'stop_agent_processing',
+    description: 'Abort a running execute_agent_command by requestId.',
+    inputSchema: {
+      type: 'object',
+      properties: { requestId: { type: 'string' } },
+      required: ['requestId']
+    }
+  },
+  {
+    name: 'encrypt_text',
+    description:
+      'Encrypt plaintext with server-side AES-256-GCM and return wrapped token as <encrypt>...</encrypt>. Use for API keys, app secrets, passwords, passkeys, and other sensitive credentials.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Plaintext to encrypt.' }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'decrypt_text',
+    description:
+      'Decrypt an <encrypt>...</encrypt> value created by encrypt_text. Use only when plaintext is required for immediate tool execution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Encrypted payload (wrapped or raw inner JSON payload).' }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'mcp_connection_create',
+    description:
+      'Normalize a new Zeus-style MCP connection (id, type streamableHttp|stdio, url or command, args, env, headers). Returns connection JSON to merge in Zeus (zeus_mcp_upsert) - MCP server does not persist the browser local graph.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        type: { type: 'string' },
+        url: { type: 'string' },
+        command: { type: 'string' },
+        args: { type: 'array', items: { type: 'string' } },
+        env: { type: 'object' },
+          headers: { type: 'object' },
+        description: { type: 'string' },
+        enabled: { type: 'boolean' }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'mcp_connection_modify',
+    description:
+      'Upsert/replace a connection in an optional mcpConnections array (pass full list as returned from Zeus zeus_mcp_list or your session); returns updated list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mcpConnections: { type: 'array', items: { type: 'object' } },
+        connection: { type: 'object' }
+      },
+      required: ['connection']
+    }
+  },
+  {
+    name: 'mcp_connection_delete',
+    description: 'Remove a connection by id (cannot delete neus-mcp). Optional mcpConnections list to filter.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' }, mcpConnections: { type: 'array', items: { type: 'object' } } },
+      required: ['id']
+    }
+  }
+];
+
+/**
+ * Names advertised on the public hosted MCP and in unauthenticated discovery (`/.well-known/*`).
+ * Extended Zeus/admin-adjacent tools are omitted unless the deployment exposes them (see mcpConfig).
+ */
+const PUBLIC_MCP_TOOL_NAMES_ORDERED = [
+  'neus_context',
+  'neus_verifiers_catalog',
+  'neus_proofs_check',
+  'neus_verify',
+  'neus_verify_or_guide',
+  'neus_proofs_get',
+  'neus_me',
+  'neus_agent_link',
+  'neus_agent_create'
+];
+const PUBLIC_MCP_TOOL_SET = new Set(PUBLIC_MCP_TOOL_NAMES_ORDERED);
+
+function toolsForPublicDiscovery() {
+  return PUBLIC_MCP_TOOL_NAMES_ORDERED.map((name) => {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+      throw new Error(`PUBLIC_MCP_TOOL_NAMES_ORDERED references missing tool: ${name}`);
+    }
+    return { name: tool.name, description: tool.description, inputSchema: tool.inputSchema };
+  });
+}
+
+/**
+ * MCP assistant instructions appended to MCP Server metadata.
+ */
+function buildMcpAssistantInstructions(exposeExtendedTools) {
+  const core = `NEUS MCP is how assistants work with NEUS proof receipts responsibly.
+
+Always call neus_context before planning any proof work so you inherit the freshest guidance, URLs, and recommended order.
+
+Products in one line: proofs are reusable trust receipts. Verification creates or refreshes those receipts across apps, agents, wallets, and organizations.
+
+Connectivity:
+- Public MCP (no Profile key on this connection): follow neus_context, list verifiers through neus_verifiers_catalog when needed, run neus_proofs_check, read public proofs with neus_proofs_get, and use neus_verify_or_guide only when setup or verification is missing.
+- Profile-connected MCP (personal access key on this MCP session): confirm with neus_me, then reuse existing receipts with account-aware reads and checks before asking for browser or signing steps.
+
+Suggested flow:
+1) neus_context
+2) neus_me when a Profile key is configured
+3) neus_agent_link when an agent wallet is involved
+4) neus_proofs_check for eligibility snapshots
+5) neus_proofs_get when exact proof records or qHashes are needed
+6) neus_verify when signing + profile prerequisites are already aligned
+7) neus_verify_or_guide only when proof, profile, payment, provider, wallet, or delegation setup is missing
+
+Guardrails:
+- Never invent qHashes, verifier IDs, statuses, eligibility, URLs, Profile fields, or tags.
+- Never ask people to paste secrets (keys, recovery phrases, OAuth tokens, passkeys).
+- Prefer silent receipt reuse. Share NEUS-hosted links only when a tool returns one because the runtime cannot complete the step.
+
+Structured signing workflows: when neus_verify returns signing material once, finalize with follow-up submissions exactly as instructed; never repeat unfinished preparation steps blindly.`;
+
+  const toolsPublic =
+    `Public MCP tools include: neus_context, neus_verifiers_catalog, neus_proofs_check, neus_verify, neus_verify_or_guide, neus_proofs_get, neus_me, neus_agent_create, neus_agent_link. Use only tools/list as the authoritative catalog.`;
+
+  const toolsExtended =
+    `This deployment exposes additional MCP tools beyond the public nine names. Inspect tools/list and follow each description. Assume nothing about internal-only capability names unless the client publishes them openly.`;
+
+  const sensitivePublic = `Treat every token like production data: encourage hosted flows and discourage pasting authorization material into chats.`;
+
+  const sensitiveExtended = `When tooling requires encrypted envelopes, preserve the <encrypt>...</encrypt> pattern mandated by deployment policy; decrypt only immediately before executing the protected action.`;
+
+  if (exposeExtendedTools) {
+    return `${core}
+
+${toolsExtended}
+
+${sensitiveExtended}`;
+  }
+  return `${core}
+
+${toolsPublic}
+
+${sensitivePublic}`;
+}
+
+const optionalString = z.string().optional();
+const optionalNumber = z.number().optional();
+const optionalBoolean = z.boolean().optional();
+
+const TOOL_ZOD_INPUT = {
+  neus_context: z.object({}).strict(),
+  neus_verifiers_catalog: z.object({}).strict(),
+  neus_proofs_check: z
+    .object({
+      wallet: z.string(),
+      verifiers: z.array(z.string()),
+      requireAll: optionalBoolean,
+      minCount: optionalNumber
+    })
+    .passthrough(),
+  neus_verify: z
+    .object({
+      walletAddress: z.string(),
+      verifierIds: z.array(z.string()),
+      data: z.record(z.string(), z.unknown()).optional(),
+      chain: optionalString,
+      signature: optionalString,
+      signedTimestamp: optionalNumber,
+      options: z.object({ returnUrl: optionalString }).optional()
+    })
+    .passthrough(),
+  neus_verify_or_guide: z
+    .object({
+      walletAddress: z.string(),
+      verifierIds: z.array(z.string()),
+      data: z.record(z.string(), z.unknown()).optional(),
+      requireAll: optionalBoolean,
+      chain: optionalString,
+      options: z.record(z.string(), z.unknown()).optional()
+    })
+    .passthrough(),
+  neus_proofs_get: z
+    .object({
+      identifier: z.string(),
+      limit: optionalNumber,
+      offset: optionalNumber,
+      tags: optionalString,
+      scope: optionalString,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString,
+      verifierId: optionalString
+    })
+    .passthrough(),
+  neus_me: z
+    .object({
+      identifier: z.string().nullish()
+    })
+    .strict(),
+  neus_agent_link: z
+    .object({
+      agentWallet: z.string(),
+      principal: optionalString
+    })
+    .passthrough(),
+  neus_agent_create: z
+    .object({
+      agentId: z.string(),
+      agentWallet: optionalString,
+      controllerWallet: optionalString,
+      agentLabel: optionalString,
+      agentType: optionalString,
+      description: optionalString,
+      capabilities: z.array(z.string()).optional(),
+      permissions: z.array(z.string()).optional(),
+      scope: optionalString,
+      expiresAt: optionalNumber,
+      maxSpend: optionalString,
+      chain: optionalString,
+      preset: optionalString,
+      instructions: optionalString,
+      skills: z.array(z.record(z.string(), z.unknown())).optional(),
+      services: z.array(z.record(z.string(), z.unknown())).optional(),
+      delegationInstructions: optionalString,
+      delegationSkills: z.array(z.record(z.string(), z.unknown())).optional()
+    })
+    .passthrough(),
+  zeus_url_fetch: z
+    .object({
+      url: z.string(),
+      maxChars: optionalNumber
+    })
+    .passthrough(),
+  zeus_execute_javascript: z
+    .object({
+      script: z.string(),
+      input: z.record(z.string(), z.unknown()).optional(),
+      timeoutMs: optionalNumber
+    })
+    .passthrough(),
+  execute_javascript_code: z
+    .object({
+      script: z.string(),
+      input: z.record(z.string(), z.unknown()).optional(),
+      timeoutMs: optionalNumber
+    })
+    .passthrough(),
+  zeus_skill_tools_list: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString
+    })
+    .passthrough(),
+  zeus_skill_tool_execute: z
+    .object({
+      qHash: z.string(),
+      input: z.record(z.string(), z.unknown()).optional(),
+      timeoutMs: optionalNumber
+    })
+    .passthrough(),
+  zeus_session_receipt_create: z
+    .object({
+      walletAddress: optionalString,
+      title: optionalString,
+      content: z.string(),
+      tags: z.array(z.string()).optional(),
+      asPrivate: optionalBoolean
+    })
+    .passthrough(),
+  zeus_session_receipt_append: z
+    .object({
+      qHash: z.string(),
+      walletAddress: optionalString,
+      appendContent: z.string(),
+      title: optionalString,
+      asPrivate: optionalBoolean
+    })
+    .passthrough(),
+  list_tools: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  list_all_available_tools: z
+    .object({})
+    .passthrough(),
+  list_memories: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  list_research: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  list_instructions: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  list_rules: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  list_mcps: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      offset: optionalNumber,
+      agentWallet: optionalString,
+      q: optionalString,
+      searchQuery: optionalString,
+      tagPrefix: optionalString,
+      tagContains: optionalString,
+      tagPrefixesAll: optionalString
+    })
+    .passthrough(),
+  get_tool: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  get_skill: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  get_memory: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  get_instruction: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  get_rule: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  get_research: z
+    .object({ qHash: optionalString, id: optionalString })
+    .passthrough(),
+  append_Content_to_memory: z
+    .object({
+      qHash: z.string(),
+      appendContent: optionalString,
+      content: optionalString,
+      walletAddress: optionalString,
+      asPrivate: optionalBoolean,
+      indexFacetKeys: z.array(z.string()).optional()
+    })
+    .passthrough(),
+  delete_revoke_memory: z
+    .object({ qHash: z.string(), walletAddress: optionalString })
+    .passthrough(),
+  list_agents: z
+    .object({
+      identifier: optionalString,
+      limit: optionalNumber,
+      agentWallet: optionalString
+    })
+    .passthrough(),
+  execute_agent_command: z
+    .object({
+      prompt: z.string(),
+      agentWallet: optionalString,
+      agentId: optionalString,
+      model: optionalString,
+      systemPrompt: optionalString,
+      temperature: optionalNumber
+    })
+    .passthrough(),
+  stop_agent_processing: z
+    .object({ requestId: z.string() })
+    .passthrough(),
+  encrypt_text: z
+    .object({ text: z.string() })
+    .passthrough(),
+  decrypt_text: z
+    .object({ text: z.string() })
+    .passthrough(),
+  mcp_connection_create: z
+    .object({
+      id: optionalString,
+      type: optionalString,
+      url: optionalString,
+      command: optionalString,
+      args: z.array(z.string()).optional(),
+      env: z.record(z.string(), z.unknown()).optional(),
+      headers: z.record(z.string(), z.unknown()).optional(),
+      description: optionalString,
+      enabled: optionalBoolean
+    })
+    .passthrough(),
+  mcp_connection_modify: z
+    .object({
+      mcpConnections: z.array(z.record(z.string(), z.unknown())).optional(),
+      connection: z.record(z.string(), z.unknown())
+    })
+    .passthrough(),
+  mcp_connection_delete: z
+    .object({ id: z.string(), mcpConnections: z.array(z.record(z.string(), z.unknown())).optional() })
+    .passthrough()
+};
+
+/**
+ * Normalize verifier ID input without aliases.
+ * Backend verifier registry is the single source of truth for accepted IDs.
+ * @param {string} verifierId - Backend verifier ID
+ * @returns {string} Trimmed verifier ID
+ */
+function normalizeVerifierId(verifierId) {
+  if (!verifierId || typeof verifierId !== 'string') return verifierId;
+  return verifierId.trim();
+}
+
+/**
+ * Map GET /api/v1/verification/verifiers JSON body to MCP context rows.
+ * API shape: { success, data: string[], metadata: { [id]: { ... } }, meta?: { ... } }
+ */
+function mapVerifierCatalogToContextList(apiBody) {
+  if (!apiBody || apiBody.error) return [];
+  const raw = apiBody.data;
+  const ids = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === 'object' && Array.isArray(raw.verifiers)
+      ? raw.verifiers
+      : [];
+  const metadata =
+    apiBody.metadata && typeof apiBody.metadata === 'object' && !Array.isArray(apiBody.metadata)
+      ? apiBody.metadata
+      : {};
+  const out = [];
+  for (const verifierId of ids) {
+    const id = String(verifierId || '').trim();
+    if (!id) continue;
+    const meta = metadata[id] || {};
+    const ds = meta.dataSchema && typeof meta.dataSchema === 'object' ? meta.dataSchema : {};
+    const requiredFields = Array.isArray(ds.required) ? ds.required.filter((x) => typeof x === 'string') : [];
+    out.push({
+      id,
+      category: meta.category,
+      description: meta.description,
+      flowType: meta.flowType,
+      expiryType: meta.expiryType,
+      requiredFields
+    });
+  }
+  return out;
+}
+
+
+function sanitizePublicMcpCopy(value) {
+  if (value == null) return undefined;
+  const s = String(value).trim();
+  if (!s) return undefined;
+  if (/\b(qHash|zeus|hostinger|trust layer|verification mcp|runtime ledger|receipt chain|hub chain|\bhub\b)\b/i.test(s)) return undefined;
+  return s;
+}
+
+function buildVerifierSummaryForPublicContext(verifiersResult) {
+  const rows = mapVerifierCatalogToContextList(verifiersResult);
+  return rows.map((v) => {
+    const row = { id: v.id };
+    const desc = sanitizePublicMcpCopy(v.description);
+    if (desc) row.description = desc.length > 480 ? `${desc.slice(0, 477)}...` : desc;
+    const cat = sanitizePublicMcpCopy(v.category);
+    if (cat) row.category = cat;
+    const flow = sanitizePublicMcpCopy(v.flowType);
+    if (flow) row.flowType = flow;
+    if (Array.isArray(v.requiredFields) && v.requiredFields.length) row.requiredFields = v.requiredFields;
+    return row;
+  });
+}
+
+
+function buildPublicNeusContextPayload(ctx, _verifiersResult) {
+  const hasBearer = !!ctx?.isAuthenticated;
+  const verifierSummary = buildVerifierSummaryForPublicContext(_verifiersResult);
+
+  return {
+    product: {
+      name: 'NEUS',
+      mcpName: 'NEUS MCP',
+      headline:
+        'NEUS turns verification into reusable proof receipts for apps, agents, gates, policies, payments, and trusted actions.',
+      summary:
+        'Create, check, read, and reuse proof receipts across apps, APIs, agents, wallets, people, organizations, and workflows.',
+      receiptModel:
+        'A proof receipt is the durable record. Verification is how a receipt is created or refreshed.'
+    },
+
+    setup: {
+      mcpEndpoint: 'https://mcp.neus.network/mcp',
+      profileUrl: 'https://neus.network/profile',
+      accessKeysUrl: 'https://neus.network/profile?tab=account',
+      hostedVerifyUrl: 'https://neus.network/verify',
+      proofUrlPattern: 'https://neus.network/proof/[proof-id]',
+      cli: {
+        install: 'npx -y -p @neus/sdk neus init',
+        auth: 'npx -y -p @neus/sdk neus auth --access-key <npk_...>',
+        status: 'npx -y -p @neus/sdk neus status --json'
+      }
+    },
+
+    mode: {
+      current: hasBearer ? 'profile-authenticated' : 'public',
+      public:
+        'No Profile access key is on this MCP session. You still get verifier lists, eligibility checks, public-scope proof reads, and hosted setup links only when something must be completed outside MCP.',
+      profileAuthenticated:
+        'A Profile access key is configured. Reuse account proof receipts, delegated reads, and matching-wallet verification paths before asking for browser or signing steps.'
+    },
+
+    goldenPath: [
+      'Call neus_context first.',
+      'If a Profile access key is configured, call neus_me.',
+      'For agents, call neus_agent_link before assuming delegation is ready.',
+      'Call neus_proofs_check for required verifier IDs before issuing anything.',
+      'If requirements are satisfied, continue without hosted verify.',
+      'Call neus_proofs_get when exact proof records, tags, Profile summary, delegated context, or qHashes are needed.',
+      'Call neus_verify only when Profile, wallet, and signing prerequisites already match.',
+      'Call neus_verify_or_guide only when proof, profile, payment, provider, wallet, or delegation setup is missing.'
+    ],
+
+    jobs: [
+      {
+        intent: 'Work with NEUS from chat',
+        use: ['neus_context'],
+        result:
+          'Load the current mode, verifier summary, and reuse-first order before choosing a tool.'
+      },
+      {
+        intent: 'Connect a NEUS Profile',
+        use: ['neus_me'],
+        result:
+          'Run after adding a Profile access key. If it fails, create an access key from setup, run the CLI auth snippet, then retry neus_me.'
+      },
+      {
+        intent: 'Check prerequisites',
+        use: ['neus_proofs_check'],
+        result: 'Eligibility snapshot only; it never creates proofs or opens hosted flows.'
+      },
+      {
+        intent: 'Reuse a receipt',
+        use: ['neus_proofs_check', 'neus_proofs_get'],
+        result:
+          'If eligible, continue silently. Use qHashes returned by neus_proofs_get when you need receipt references.'
+      },
+      {
+        intent: 'Finish missing setup',
+        use: ['neus_verify_or_guide'],
+        result:
+          'Use only after reuse checks show something is missing or requires browser-only consent, provider login, wallet signing, payment, or delegation setup.'
+      },
+      {
+        intent: 'Understand existing proofs',
+        use: ['neus_proofs_get'],
+        result: 'Use returned proof records and qHashes; do not infer proof state from memory.'
+      },
+      {
+        intent: 'Set up an agent',
+        use: ['neus_agent_create', 'neus_agent_link'],
+        result:
+          'Complete onboarding in order. Optional skills/services are descriptive metadata — they are never secret keys.'
+      }
+    ],
+
+    tools: {
+      neus_context:
+        'Session home: setup, Profile access-key mode, verifier summaries, reuse-first workflow, tools, and safety rules. Always first.',
+      neus_verifiers_catalog:
+        'Full verifier directory with schemas; after neus_context when you need payload fields beyond the summary.',
+      neus_proofs_check: 'Checks existing proofs versus verifier IDs. Eligibility only; never mints proofs.',
+      neus_verify:
+        'Creates or continues verification only when Profile, wallet, and signing already satisfy NEUS.',
+      neus_verify_or_guide:
+        'Fallback when proof, profile, payment, provider, wallet, or delegation setup is missing; hosted URLs only when required.',
+      neus_proofs_get:
+        'Proof records, tags, optional delegated reads, Profile fields, live state — IDs in the payload are authoritative.',
+      neus_me:
+        'Signed-in Profile only when this MCP session has a personal access key from Profile  —  Account.',
+      neus_agent_create:
+        'Prepares identity and delegation payloads; confirm with neus_agent_link after signing. Skills/services are metadata — not secrets.',
+      neus_agent_link:
+        'Readiness for agent wallet: linked when identity and delegation proofs exist; otherwise next hosted step.'
+    },
+
+    proofModel: {
+      language: 'Prefer qHash, proof record, proof state, proof URL wording with people.',
+      sourceOfTruth:
+        'Treat NEUS responses as authoritative. Never synthesize proofs, statuses, URLs, Profile fields, or tags.',
+      hostedFallback:
+        'Use hosted links only when a NEUS tool returns one because the step cannot be completed inside MCP.'
+    },
+
+    agentModel: {
+      identity: 'Proof that pins the operational wallet plus how the agent introduces itself.',
+      delegation: 'Proof showing which controller wallet trusts the agent wallet.',
+      skills:
+        'Metadata rows that advertise capabilities — they never replace approvals, secrets, or real credentials.'
+    },
+
+    safetyRules: [
+      'Re-query tools whenever facts might have changed — do not cache verifier outcomes, proofs, eligibility, URLs, Profile fields, or tags across long conversations.',
+      'Never ask anyone to paste private keys, NEUS personal access keys, wallet recovery phrases, API keys, OAuth tokens, passwords, passkeys, or session cookies.',
+      'When user action is required, share NEUS-hosted links returned by tools; do not manufacture URLs or prompt before reuse checks.',
+      'If richer access fails, remind people Profile access keys are created under Profile  —  Account and must be wired into their MCP client.',
+      'Prefer neus_verifiers_catalog for payload ambiguity and neus_proofs_get for live inventory — guesswork is forbidden.'
+    ],
+
+    verifierSummary
+  };
+}
+
+// ============================================================================
+// ERROR REMEDIATION (actionable guidance for common errors)
+// ============================================================================
+
+const ERROR_REMEDIATION = {
+  'VERIFIER_NOT_FOUND': {
+    action: 'Re-open neus_verifiers_catalog and copy the verifier id verbatim.',
+    hint: 'Identifiers are lowercase slugs supplied by NEUS — not guessed names.'
+  },
+  'WALLET_NOT_FOUND': {
+    action: 'Validate the wallet or DID formatting before retrying.',
+    hint: 'EVM wallets start with 0x plus 40 hex characters; Solana addresses are base58; DIDs begin with did:pkh:'
+  },
+  'CHAIN_CONTEXT_MISMATCH': {
+    action: 'Make sure optional network hints match the wallet type you supplied.',
+    hint: 'EVM tooling typically uses CAIP-style eip155 references; Solana uses solana:mainnet.'
+  },
+  'SIGNATURE_REQUIRED': {
+    action: 'The approver still needs to sign — use neus_verify_or_guide if they should complete steps in-browser.',
+    hint: 'NEUS returns signer text on the preparation response; finalize with exactly one follow-up call.'
+  },
+  'SESSION_EXPIRED': {
+    action: 'Ask the participant to reopen https://neus.network/verify and finish sign-in.',
+    hint: 'Short-lived auth codes expire quickly; fresh sessions pick up afterward.'
+  },
+  'RATE_LIMITED': {
+    action: 'Pause briefly before retrying, or elevate to a billing-backed path if quotas demand it.',
+    hint: 'NEUS rate limits defend shared infrastructure.'
+  },
+  'INSUFFICIENT_CREDITS': {
+    action: 'Fund the workspace or retry after NEUS acknowledges payment.',
+    hint: 'Credits cover verification throughput — see billing messaging from NEUS APIs.'
+  },
+  'PAYMENT_REQUIRED': {
+    action: 'Follow the billing handshake NEUS returns, then resubmit unchanged parameters.',
+    hint: 'Use the hosted billing link if one is surfaced in the payload.'
+  },
+  'VALIDATION_ERROR': {
+    action: 'Align arguments with schemas from tools/list and neus_verifiers_catalog.',
+    hint: 'Missing required fields appear on the verifier entry.'
+  },
+  'AUTH_REQUIRED': {
+    action: 'Add a NEUS personal access key to the MCP Authorization header or move the participant to guided verification.',
+    hint: 'Create keys from Profile  —  Account and configure the client exactly as documented.'
+  }
+};
+
+// ============================================================================
+// CHAIN RESOLUTION  —  defaults from deployment configuration
+// ============================================================================
+
+const HUB_CHAIN_ID = mcp.hubChainId;
+const HUB_CHAIN = `eip155:${HUB_CHAIN_ID}`;
+const SOLANA_MAINNET = 'solana:mainnet';
+/**
+ * Detect wallet type from address format
+ * @param {string} address - Wallet address
+ * @returns {'evm'|'solana'|'unknown'}
+ */
+function detectWalletType(address) {
+  if (!address || typeof address !== 'string') return 'unknown';
+  const trimmed = address.trim();
+  // EVM: 0x followed by 40 hex chars
+  if (/^0x[a-fA-F0-9]{40}$/i.test(trimmed)) return 'evm';
+  // Solana: base58, typically 32-44 chars, no 0x prefix
+  if (/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(trimmed)) return 'solana';
+  return 'unknown';
+}
+
+/**
+ * Resolve identifier (wallet or DID) to DID and wallet address
+ * @param {string} identifier - Wallet address or DID
+ * @returns {{ did: string, walletAddress: string } | { error: string }}
+ */
+function resolveIdentifierToDid(identifier) {
+  if (!identifier || typeof identifier !== 'string') return { error: 'identifier is required' };
+  const trimmed = identifier.trim();
+  if (trimmed.startsWith('did:pkh:')) {
+    const parts = trimmed.split(':');
+    if (parts.length >= 5) {
+      const namespace = parts[2];
+      const walletAddress = namespace === 'eip155'
+        ? parts.slice(4).join(':').toLowerCase()
+        : parts.slice(4).join(':');
+      return { did: trimmed, walletAddress };
+    }
+  }
+  const walletType = detectWalletType(trimmed);
+  if (walletType === 'evm') {
+    const walletAddress = trimmed.toLowerCase();
+    return { did: `did:pkh:eip155:${HUB_CHAIN_ID}:${walletAddress}`, walletAddress };
+  }
+  if (walletType === 'solana') {
+    return { did: `did:pkh:solana:mainnet:${trimmed}`, walletAddress: trimmed };
+  }
+  return { error: 'Invalid identifier format. Use EVM address (0x...), Solana address, or DID (did:pkh:...)' };
+}
+
+/**
+ * Resolve CAIP-2 chain identifier from wallet address
+ * - EVM addresses default to the configured protocol hub chain
+ * - Solana addresses use solana:mainnet
+ * - Explicit chain parameter takes precedence if valid
+ * @param {string} walletAddress
+ * @param {string} [explicitChain] - Optional explicit CAIP-2 chain
+ * @returns {string} CAIP-2 chain identifier
+ */
+function resolveChain(walletAddress, explicitChain) {
+  // If explicit chain provided and valid, use it
+  if (typeof explicitChain === 'string' && explicitChain.trim().length > 0) {
+    return explicitChain.trim();
+  }
+  // Auto-detect from wallet address
+  const walletType = detectWalletType(walletAddress);
+  if (walletType === 'solana') return SOLANA_MAINNET;
+  // Default to EVM hub chain
+  return HUB_CHAIN;
+}
+
+function normalizeWalletForMcp(address) {
+  if (!address || typeof address !== 'string') return null;
+  const trimmed = address.trim();
+  const walletType = detectWalletType(trimmed);
+  if (walletType === 'evm') return trimmed.toLowerCase();
+  if (walletType === 'solana') return trimmed;
+  return trimmed;
+}
+
+function mcpAgentDelegationHeaders(agentWallet) {
+  const aw = agentWallet ? normalizeWalletForMcp(String(agentWallet)) : null;
+  return aw ? { 'x-agent-wallet': aw } : {};
+}
+
+function normalizeStringArray(input) {
+  if (!Array.isArray(input)) return [];
+  return input.map((value) => (typeof value === 'string' ? value.trim() : '')).filter(Boolean);
+}
+
+function scopeToProofTagsQuery(scopeRaw) {
+  const s = String(scopeRaw || '').trim().toLowerCase();
+  if (!s) return '';
+  if (s === 'memory') return 'memory';
+  if (s === 'research') return 'research';
+  if (s === 'rules') return 'rule,rules';
+  if (s === 'instruction') return 'instruction,instructions';
+  if (s === 'tools') return 'tool,skill,agent:tool,agent:skill';
+  if (s === 'receipts' || s === 'receipt') return 'receipt:chat,receipt:session,receipt:reference';
+  return '';
+}
+
+function proofOptionsForVisibility(visibility) {
+  if (visibility === 'private') return { privacyLevel: 'private', publicDisplay: false };
+  if (visibility === 'public') return { privacyLevel: 'public', publicDisplay: true };
+  return { privacyLevel: 'public', publicDisplay: false };
+}
+
+function isBlockedZeusFetchHost(hostname) {
+  const h = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (h === 'localhost' || h === '0.0.0.0' || h === '::1' || h === '::' || h === 'metadata.google.internal') return true;
+  if (h.endsWith('.local') || h.endsWith('.lan') || h.endsWith('.internal')) return true;
+  if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (/^172\.(1[6-9]|2[0-9]|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (h.startsWith('169.254.') || h.startsWith('fe80:') || h.startsWith('fc00:') || h.startsWith('fd')) return true;
+  return false;
+}
+
+function getProofQHash(proof) {
+  const raw = String(proof?.qHash || proof?.id || '').trim().toLowerCase();
+  if (!raw) return '';
+  const with0x = raw.startsWith('0x') ? raw : `0x${raw}`;
+  return /^0x[a-f0-9]{64}$/.test(with0x) ? with0x : '';
+}
+
+function getProofTitle(proof) {
+  return String(proof?.title || proof?.meta?.title || proof?.reference?.title || proof?.verifierLabel || proof?.verifierId || 'Proof').trim();
+}
+
+function getProofTags(proof) {
+  const sources = [proof?.meta?.tags, proof?.tags, proof?.options?.tags];
+  return Array.from(new Set(sources.flatMap((value) => (Array.isArray(value) ? value : typeof value === 'string' ? [value] : [])).map(String).map((x) => x.trim()).filter(Boolean)));
+}
+
+function getProofContentText(rawProof) {
+  const proof = rawProof?.data && typeof rawProof.data === 'object' ? rawProof.data : rawProof;
+  const candidates = [
+    proof?.content,
+    proof?.data?.content,
+    proof?.publicContent?.content,
+    proof?.privateContent?.content,
+    proof?.reference?.description,
+    proof?.meta?.description
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate;
+  }
+  return '';
+}
+
+/**
+ * Unwrap BFF-style proof record { data: { ... } } for tag/qHash reads.
+ * @param {unknown} raw
+ * @returns {object|null}
+ */
+function unwrapApiProofRecord(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (raw.data && typeof raw.data === 'object' && !Array.isArray(raw.data)) {
+    const d = /** @type {Record<string, unknown>} */ (raw.data);
+    return { ...raw, ...d, qHash: d.qHash || raw.qHash, meta: d.meta || raw.meta, options: d.options || raw.options };
+  }
+  return /** @type {object} */ (raw);
+}
+
+/**
+ * @param {string} t
+ * @param {'tool'|'skill'|'memory'|'research'|'instruction'|'rule'} category
+ */
+function tagMatchesCategory(t, category) {
+  const s = String(t || '')
+    .trim()
+    .toLowerCase();
+  if (!s) return false;
+  switch (category) {
+    case 'tool':
+      return s === 'tool' || s === 'agent:tool' || s.startsWith('tool:');
+    case 'skill':
+      return s === 'skill' || s === 'agent:skill' || s.startsWith('skill:');
+    case 'memory':
+      return s === 'memory' || s.startsWith('memory:');
+    case 'research':
+      return s === 'research' || s.startsWith('research:');
+    case 'instruction':
+      return s === 'instruction' || s === 'instructions' || s.startsWith('instruction:');
+    case 'rule':
+      return s === 'rule' || s === 'rules' || s.startsWith('rules:');
+    default:
+      return false;
+  }
+}
+
+/**
+ * @param {unknown} rawProof
+ * @param {'tool'|'skill'|'memory'|'research'|'instruction'|'rule'} category
+ */
+function proofMatchesCategory(rawProof, category) {
+  const p = unwrapApiProofRecord(rawProof) || (typeof rawProof === 'object' && rawProof ? rawProof : null);
+  if (!p) return false;
+  const tags = getProofTags(p);
+  for (const t of tags) {
+    if (tagMatchesCategory(t, category)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {Record<string, unknown>|undefined} rec
+ * @returns {object|null}
+ */
+function normalizeMcpConnectionEntry(rec) {
+  if (!rec || typeof rec !== 'object') return null;
+  const id = String(rec.id || '').trim();
+  const command = String(rec.command || '').trim();
+  const url = String(rec.url || '').trim();
+  const inferred = command ? 'stdio' : url ? 'streamablehttp' : '';
+  const typeRaw = String(rec.type || inferred || '')
+    .trim()
+    .toLowerCase();
+  if (!id) return null;
+  if (typeRaw !== 'streamablehttp' && typeRaw !== 'stdio') return null;
+  const type = typeRaw === 'streamablehttp' ? 'streamableHttp' : 'stdio';
+  const out = { id, type };
+  if (url) out.url = url;
+  if (command) out.command = command;
+  const a = normalizeStringArray(rec.args);
+  if (a.length) out.args = a;
+  const env = rec.env;
+  if (env && typeof env === 'object' && !Array.isArray(env)) {
+    const e = /** @type {Record<string, string>} */ ({});
+    for (const [k, v] of Object.entries(/** @type {Record<string, unknown>} */ (env))) {
+      const key = String(k).trim();
+      if (!key) continue;
+      e[key] = v == null ? '' : String(v);
+    }
+    if (Object.keys(e).length) out.env = e;
+  const headers = rec.headers;
+  if (headers && typeof headers === 'object' && !Array.isArray(headers)) {
+    const h = /** @type {Record<string, string>} */ ({});
+    for (const [k, v] of Object.entries(/** @type {Record<string, unknown>} */ (headers))) {
+      const key = String(k).trim();
+      if (!key) continue;
+      h[key] = v == null ? '' : String(v);
+    }
+    if (Object.keys(h).length) out.headers = h;
+  }
+  }
+  const description = String(rec.description || '').trim();
+  if (description) out.description = description;
+  if (typeof rec.enabled === 'boolean') out.enabled = rec.enabled;
+  return out;
+}
+
+/**
+ * @param {ReturnType<typeof createSessionCtx>} ctx
+ * @param {object} args
+ * @param {string} tagsComma
+ */
+async function fetchProofTitleIdMap(ctx, args, tagsComma) {
+  const identifier = String(args?.identifier || '').trim() || (await resolveAuthenticatedWallet(ctx));
+  if (!identifier) {
+    return { error: 'validation_error', message: 'identifier or Bearer profile wallet required' };
+  }
+  const limit = Math.min(Math.max(1, Number(args?.limit) || 200), 250);
+  const offset = Math.max(0, Number(args?.offset) || 0);
+  const query = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+  if (tagsComma) {
+    const normalized = tagsComma
+      .split(',')
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean)
+      .join(',');
+    if (normalized) query.set('tags', normalized);
+  }
+  const qRaw = String(args?.q || args?.searchQuery || '').trim();
+  if (qRaw) query.set('q', qRaw.slice(0, 280));
+  if (!ctx.isAuthenticated) query.set('isPublicRead', '1');
+  const result = await ctx.callApi(
+    `/api/v1/proofs/by-wallet/${encodeURIComponent(identifier)}?${query.toString()}`,
+    { headers: mcpAgentDelegationHeaders(args?.agentWallet) }
+  );
+  if (result?.error) return result;
+  const proofs = Array.isArray(result?.data?.proofs)
+    ? result.data.proofs
+    : Array.isArray(result?.proofs)
+      ? result.proofs
+      : Array.isArray(result?.data)
+        ? result.data
+        : [];
+  const tagPrefix = String(args?.tagPrefix || '')
+    .trim()
+    .toLowerCase();
+  const tagContains = String(args?.tagContains || '')
+    .trim()
+    .toLowerCase();
+  const tagPrefixesAll = String(args?.tagPrefixesAll || '')
+    .trim()
+    .toLowerCase();
+  const dict = Object.create(null);
+  const items = [];
+  for (const pr of proofs) {
+    const id = getProofQHash(pr);
+    const title = getProofTitle(pr);
+    if (!id) continue;
+    const tags = getProofTags(pr).map((t) => String(t).toLowerCase());
+    if (tagPrefix && !tags.some((t) => t.startsWith(tagPrefix))) continue;
+    if (tagContains && !tags.some((t) => t.includes(tagContains))) continue;
+    if (tagPrefixesAll && !proofTagsMatchAllPrefixes(tags, tagPrefixesAll)) continue;
+    items.push({ id, title, tags: getProofTags(pr) });
+    dict[title] = id;
+  }
+  return { success: true, items, dictionary: dict, count: items.length };
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {string} normalized 0x+64 or ''
+ */
+function normalizeQHashInput(raw) {
+  const a = String(raw || '').trim();
+  if (!a) return '';
+  const lower = a.toLowerCase();
+  const h = lower.startsWith('0x') ? lower : `0x${lower.replace(/^0x/i, '')}`;
+  return /^0x[a-f0-9]{64}$/.test(h) ? h : '';
+}
+
+/**
+ * @param {object} args
+ * @param {ReturnType<typeof createSessionCtx>} ctx
+ * @param {'tool'|'skill'|'memory'|'research'|'instruction'|'rule'} category
+ */
+async function getCategorizedProofByHash(args, ctx, category) {
+  const qHash = normalizeQHashInput(args?.qHash || args?.id);
+  if (!qHash) return { error: 'validation_error', message: 'qHash or id (0x + 64 hex chars) is required' };
+  const raw = await ctx.callApi(`/api/v1/proofs/${encodeURIComponent(qHash)}`);
+  if (raw?.error) return raw;
+  if (!proofMatchesCategory(raw, category)) {
+    return { error: 'validation_error', message: `Proof is not in category "${category}" (check tags).` };
+  }
+  const un = unwrapApiProofRecord(raw) || raw;
+  return {
+    success: true,
+    qHash: getProofQHash(un) || qHash,
+    title: getProofTitle(un),
+    tags: getProofTags(un),
+    content: getProofContentText(un),
+    record: un
+  };
+}
+
+function parseSkillToolProofSections(rawContent) {
+  const content = String(rawContent || '');
+  const match = /(?:^|\n)-{5,}\s*\n/.exec(content);
+  if (!match) return { summaryMarkdown: content.trim(), script: '', separatorFound: false };
+  const splitAt = match.index + (match[0].startsWith('\n') ? 1 : 0);
+  const separatorLength = match[0].length - (match[0].startsWith('\n') ? 1 : 0);
+  return {
+    summaryMarkdown: content.slice(0, splitAt).trim(),
+    script: content.slice(splitAt + separatorLength).trim(),
+    separatorFound: true
+  };
+}
+
+/**
+ * Run tool/proof JavaScript: async/await, optional require('nodemailer'), no full process.env (Gmail keys only).
+ * @param {string} script
+ * @param {unknown} input
+ * @param {number|undefined} timeoutMs
+ * @returns {Promise<{ value: unknown, logs: string[] }>}
+ */
+async function runZeusSandbox(script, input, timeoutMs) {
+  const safeTimeout = Math.max(250, Math.min(15000, Number(timeoutMs) || 4000));
+  const logs = [];
+  const sandbox = {
+    input: input && typeof input === 'object' ? input : {},
+    result: undefined,
+    require: requireInZeusSandbox,
+    process: { env: zeusSandboxGmailProcessEnv() },
+    console: {
+      log: (...a) => logs.push(a.map((x) => String(x)).join(" ")),
+      warn: (...a) => logs.push(`[warn] ${a.map((x) => String(x)).join(" ")}`),
+      error: (...a) => logs.push(`[error] ${a.map((x) => String(x)).join(" ")}`),
+    },
+    // Expose Node.js built-ins available from Node 18+ so scripts can call external APIs (Brave Search, etc.)
+    // while still being restricted by requireInZeusSandbox on module imports.
+    fetch: globalThis.fetch,
+    URL: globalThis.URL,
+  };
+  const context = vm.createContext(sandbox, { name: 'zeus-mcp-tool' });
+  const userSource = String(script || '');
+  const wrapped = `(async () => {\n${userSource}\n})();`;
+  const scriptObject = new vm.Script(wrapped, { filename: 'zeus-mcp-execute.mjs' });
+  let runResult;
+  try {
+    runResult = scriptObject.runInContext(context, { timeout: safeTimeout });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`Script parse or sync error: ${message}`);
+  }
+  const output = await Promise.race([
+    Promise.resolve(runResult),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('Script timed out')), safeTimeout))
+  ]);
+  const finalOutput = typeof output === 'undefined' ? sandbox.result : output;
+  return { value: finalOutput, logs };
+}
+
+async function resolveReceiptWallet(args, ctx) {
+  const explicit = normalizeWalletForMcp(String(args?.walletAddress || '').trim());
+  if (explicit) return explicit;
+  const authed = await resolveAuthenticatedWallet(ctx);
+  return authed || null;
+}
+
+/** Profile wallet from Bearer PAT or cookie  —  both hit /auth/me; same principal, not an extra session layer. */
+async function resolveAuthenticatedWallet(ctx) {
+  if (!ctx?.isAuthenticated) return null;
+  try {
+    const meResult = await ctx.callApi('/api/v1/auth/me');
+    if (typeof meResult?.data?.address === 'string' && meResult.data.address.trim()) {
+      return normalizeWalletForMcp(meResult.data.address);
+    }
+    if (typeof meResult?.data?.primaryAccount === 'string' && meResult.data.primaryAccount.trim()) {
+      return normalizeWalletForMcp(meResult.data.primaryAccount);
+    }
+  } catch {
+    // Ignore lookup failures and fall back to explicit inputs.
+  }
+  return null;
+}
+
+async function resolvePrincipalWallet(principal, ctx) {
+  if (typeof principal === 'string' && principal.trim()) {
+    const resolved = resolveIdentifierToDid(principal.trim());
+    if (resolved?.error) {
+      return { error: 'validation_error', message: resolved.error };
+    }
+    return { walletAddress: normalizeWalletForMcp(resolved.walletAddress) };
+  }
+
+  return { walletAddress: await resolveAuthenticatedWallet(ctx) };
+}
+
+function buildAgentHostedVerifyUrl(agentWallet, controllerWallet = null) {
+  const params = new URLSearchParams({
+    verifiers: 'agent-identity,agent-delegation',
+    agentWallet: normalizeWalletForMcp(agentWallet) || String(agentWallet || '').trim()
+  });
+  if (controllerWallet) {
+    params.set('controllerWallet', controllerWallet);
+  }
+  return `https://neus.network/verify?${params.toString()}`;
+}
+
+// ============================================================================
+// API HELPERS
+// ============================================================================
+
+/**
+ * Call NEUS API with proper headers and timeout.
+ * Auth resolution order: options.bearerToken > process-global NEUS_AUTH_TOKEN.
+ */
+async function callNeusApi(endpoint, options = {}) {
+  const url = `${NEUS_API_URL}${endpoint}`;
+  const bearerToken = options.bearerToken;
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Neus-App': MCP_APP_ID,
+    'X-Neus-Mcp': 'true',
+    ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+    ...options.headers
+  };
+
+  const maxRetries = Number.isFinite(Number(options.maxRetries))
+    ? Math.max(0, Number(options.maxRetries))
+    : API_MAX_RETRIES;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
+    const method = options.method || 'GET';
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+
+      // Handle 402 Payment Required (x402 standardized contract)
+      if (response.status === 402) {
+        const paymentRequiredRaw = response.headers.get('PAYMENT-REQUIRED');
+        let paymentRequired = null;
+        if (paymentRequiredRaw) {
+          try {
+            paymentRequired = JSON.parse(paymentRequiredRaw);
+          } catch {
+            paymentRequired = null;
+          }
+        }
+        const data = await response.json().catch(() => ({}));
+        if (!paymentRequired && data?.x402 && typeof data.x402 === 'object') {
+          paymentRequired = data.x402;
+        }
+        const requiredCreditsRaw =
+          paymentRequired?.requiredCredits ??
+          paymentRequired?.creditsRequired ??
+          data?.requiredCredits ??
+          data?.error?.requiredCredits ??
+          null;
+        const requiredCredits = Number.isFinite(Number(requiredCreditsRaw))
+          ? Number(requiredCreditsRaw)
+          : null;
+        const pricingUrl = typeof paymentRequired?.pay?.pricing === 'string'
+          ? paymentRequired.pay.pricing
+          : (typeof paymentRequired?.pricingUrl === 'string' ? paymentRequired.pricingUrl : null);
+        const reason = typeof paymentRequired?.reason === 'string'
+          ? paymentRequired.reason
+          : (typeof data?.error?.code === 'string' ? data.error.code : 'payment_required');
+        const message = data?.error?.message || data?.message || 'Payment required. Complete the NEUS billing step, then retry.';
+        const receiptHeader = typeof paymentRequired?.receiptHeader === 'string'
+          ? paymentRequired.receiptHeader
+          : 'PAYMENT-SIGNATURE';
+        const hostedCheckoutUrl = 'https://neus.network/verify';
+        return {
+          error: 'payment_required',
+          reason,
+          message,
+          status: 402,
+          requiredCredits,
+          pricingUrl,
+          hostedCheckoutUrl,
+          receiptHeader,
+          suggestedNextAction: `Fulfill billing through NEUS (header ${receiptHeader} when instructed), then repeat the MCP call unchanged. Hosted checkout stays available at ${hostedCheckoutUrl}.`
+        };
+      }
+
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        const errorCode = data.error?.code || 'api_error';
+        const remediation = ERROR_REMEDIATION[errorCode?.toUpperCase()] || null;
+        const mappedError = {
+          error: errorCode,
+          message: data.error?.message || data.message || `API error: ${response.status}`,
+          status: response.status,
+          statusCode: response.status,
+          ...(remediation && { remediation }),
+          ...(response.status === 409 && data?.error?.details?.nextStep
+            ? { nextStep: data.error.details.nextStep }
+            : {})
+        };
+        if (shouldRetryStatus(response.status) && attempt < maxRetries) {
+          const delayMs = API_RETRY_BASE_MS * (2 ** attempt);
+          log('warn', 'mcp_api_retry_status', { endpoint, method, attempt, status: response.status, delayMs });
+          await sleep(delayMs);
+          continue;
+        }
+        return mappedError;
+      }
+      return data;
+    } catch (fetchError) {
+      clearTimeout(timeoutId);
+      const isAbort = fetchError?.name === 'AbortError';
+      const canRetry = attempt < maxRetries && (isAbort || shouldRetryError(fetchError));
+      if (canRetry) {
+        const delayMs = API_RETRY_BASE_MS * (2 ** attempt);
+        log('warn', 'mcp_api_retry_error', {
+          endpoint,
+          method,
+          attempt,
+          error: fetchError?.message || 'unknown_error',
+          code: fetchError?.code || null,
+          delayMs
+        });
+        await sleep(delayMs);
+        continue;
+      }
+      if (isAbort) {
+        return {
+          error: 'timeout',
+          message: 'Request timeout after 5 minutes',
+          status: 504,
+          statusCode: 504
+        };
+      }
+      throw fetchError;
+    }
+  }
+}
+
+// ============================================================================
+// SESSION CONTEXT
+// ============================================================================
+
+/**
+ * Create a request-scoped session context.
+ * Auth resolution: per-session bearer > process-global NEUS_AUTH_TOKEN.
+ * @param {string[]|null} exposedToolNames - Tool names registered for this session (tools/list + list_all_available_tools).
+ */
+function createSessionCtx(sessionBearerToken, exposedToolNames = null) {
+  const bearerToken = sessionBearerToken;
+  return {
+    bearerToken,
+    isAuthenticated: !!bearerToken,
+    exposedToolNames: exposedToolNames || [...PUBLIC_MCP_TOOL_NAMES_ORDERED],
+    callApi(endpoint, options = {}) {
+      return callNeusApi(endpoint, { ...options, bearerToken });
+    }
+  };
+}
+
+// ============================================================================
+// TOOL HANDLERS
+// ============================================================================
+
+const handlers = {
+  async neus_verifiers_catalog(_args, ctx) {
+    const result = await ctx.callApi('/api/v1/verification/verifiers');
+    const data = result?.data;
+    if (Array.isArray(data)) {
+      return data;
+    }
+    // Defensive fallback for unexpected API shapes
+    log('warn', 'mcp_verifiers_catalog_unexpected_shape', {
+      type: typeof data,
+      isArray: Array.isArray(data),
+      keys: data && typeof data === 'object' ? Object.keys(data) : null
+    });
+    return [];
+  },
+
+  // Gate Check Tools (v1-safe: eligibility-only)
+  async neus_proofs_check(args, ctx) {
+    const { wallet, verifiers, requireAll, minCount, handle, namespace } = args;
+    const params = new URLSearchParams();
+    const canonicalVerifiers = Array.isArray(verifiers)
+      ? verifiers.map(v => normalizeVerifierId(v))
+      : [normalizeVerifierId(String(verifiers || ''))];
+    params.set('address', wallet);
+    params.set('verifierIds', canonicalVerifiers.join(','));
+    if (requireAll === true) params.set('requireAll', 'true');
+    if (Number.isFinite(Number(minCount)) && Number(minCount) > 0) params.set('minCount', String(Number(minCount)));
+    if (handle && typeof handle === 'string' && handle.trim()) params.set('handle', handle.trim());
+    if (namespace && typeof namespace === 'string' && namespace.trim()) {
+      params.set('namespace', namespace.trim().toLowerCase());
+    }
+
+    const result = await ctx.callApi(`/api/v1/proofs/check?${params.toString()}`);
+
+    // SECURITY: Never return qHash lists or projections from gate checks via MCP.
+    const eligible = Boolean(result?.data?.eligible);
+    const matchedCount = Number.isFinite(Number(result?.data?.matchedCount)) ? Number(result.data.matchedCount) : 0;
+    return {
+      success: result?.success === true,
+      eligible,
+      matchedCount
+    };
+  },
+
+  async neus_verify(args, ctx) {
+    const {
+      walletAddress,
+      verifierIds,
+      data: dataArg,
+      chain,
+      signature,
+      signedTimestamp,
+      options = {}
+    } = args || {};
+    const data =
+      dataArg && typeof dataArg === 'object' && !Array.isArray(dataArg) ? dataArg : {};
+
+    if (!walletAddress || typeof walletAddress !== 'string') {
+      return { error: 'validation_error', message: 'walletAddress is required' };
+    }
+    if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
+      return { error: 'validation_error', message: 'verifierIds array with at least one ID is required' };
+    }
+
+    const idResolve = resolveIdentifierToDid(String(walletAddress).trim());
+    if (idResolve?.error) {
+      return { error: 'validation_error', message: idResolve.error };
+    }
+    const subjectForUnsigned = idResolve.walletAddress;
+
+    const canonicalVerifierIds = verifierIds.map(v => normalizeVerifierId(v));
+
+    // Auto-detect chain from wallet address format
+    const resolvedChain = resolveChain(subjectForUnsigned, chain);
+
+    const ts = Number.isFinite(Number(signedTimestamp)) && Number(signedTimestamp) > 0
+      ? Number(signedTimestamp)
+      : Date.now();
+
+    // Signature missing: authenticated principal (Bearer PAT or cookie via same /auth/me) matches wallet  —  API signatureless POST
+    if (!signature || typeof signature !== 'string' || signature.trim().length === 0) {
+      const claimedWallet = normalizeWalletForMcp(subjectForUnsigned);
+      if (ctx.isAuthenticated && claimedWallet) {
+        const principalWallet = await resolveAuthenticatedWallet(ctx);
+        if (principalWallet && principalWallet === claimedWallet) {
+          const verifyBodySession = {
+            walletAddress: subjectForUnsigned,
+            verifierIds: canonicalVerifierIds,
+            data,
+            chain: resolvedChain,
+            options
+          };
+          const verifyResult = await ctx.callApi('/api/v1/verification', {
+            method: 'POST',
+            body: verifyBodySession
+          });
+
+          if (verifyResult?.status === 409 && verifyResult?.nextStep) {
+            return {
+              error: verifyResult.error,
+              message: verifyResult.message,
+              status: 409,
+              nextStep: verifyResult.nextStep,
+              path: 'principal_direct'
+            };
+          }
+
+          if (verifyResult?.error) {
+            return {
+              error: verifyResult.error,
+              message: verifyResult.message || 'Verification failed',
+              path: 'principal_direct',
+              hint:
+                'If this verifier requires browser-only consent, provider login, payment, or wallet setup, call neus_verify_or_guide and use the returned hostedVerifyUrl.'
+            };
+          }
+
+          const qHashS = verifyResult?.data?.qHash;
+          if (qHashS) log('info', 'mcp_qhash_produced', { tool: 'neus_verify', path: 'principal_direct' });
+
+          return {
+            success: verifyResult?.success === true,
+            status: verifyResult?.data?.status,
+            qHash: qHashS,
+            path: 'principal_direct',
+            message: 'Proof request submitted using authenticated API principal (Bearer or cookie; no separate wallet signature).'
+          };
+        }
+
+        if (principalWallet && principalWallet !== claimedWallet) {
+          return {
+            error: 'wallet_session_mismatch',
+            message:
+              'Bearer is for a different NEUS profile wallet than walletAddress. Use an access key for the matching profile, switch walletAddress to the profile wallet, or use the hosted URL returned by neus_verify_or_guide.',
+            next_action: 'hosted_login_or_browser_or_sign',
+            hostedLoginUrl: 'https://neus.network/verify?intent=login'
+          };
+        }
+      }
+
+      const standardizeBody = {
+        walletAddress: subjectForUnsigned,
+        verifierIds: canonicalVerifierIds,
+        data,
+        signedTimestamp: ts,
+        chain: resolvedChain
+      };
+
+      const standardizeResult = await ctx.callApi('/api/v1/verification/standardize', {
+        method: 'POST',
+        body: standardizeBody
+      });
+
+      if (standardizeResult?.error) return { error: standardizeResult.error, message: standardizeResult.message || 'Signing string generation failed' };
+
+      const signerString = standardizeResult?.data?.signerString;
+      const standardizedChain = standardizeResult?.data?.bodyPreview?.chain || resolvedChain;
+      if (signerString) log('info', 'mcp_elicitation_generated', { tool: 'neus_verify' });
+
+      const base = 'https://neus.network/verify';
+      const params = new URLSearchParams({ verifiers: canonicalVerifierIds.join(',') });
+      const returnUrl = typeof options?.returnUrl === 'string' ? options.returnUrl.trim() : null;
+      if (returnUrl) params.set('returnUrl', returnUrl);
+      const hostedVerifyUrl = `${base}?${params.toString()}`;
+
+      const sigVersion = standardizeResult?.data?.sigVersion ?? null;
+      const bodyPreview = standardizeResult?.data?.bodyPreview ?? null;
+
+      return {
+        status: 'verification_required',
+        next_action: 'verify',
+        path: 'standardize_or_browser',
+        standardizeAlreadyApplied: true,
+        elicitation: {
+          required: true,
+          mode: 'url_or_sign',
+          message:
+            'Prefer an access key whose profile wallet matches walletAddress. If browser-only consent, provider login, payment, or wallet setup is required, open hostedVerifyUrl. If you already have the signer available, sign signerString and call neus_verify again with the same walletAddress, verifierIds, data, signedTimestamp, chain, plus signature.',
+          signerString,
+          signedTimestamp: ts,
+          chain: standardizedChain,
+          hostedVerifyUrl,
+          sigVersion,
+          bodyPreview
+        }
+      };
+    }
+
+    // Signature provided: call verification endpoint
+    const verifyBody = {
+      walletAddress,
+      verifierIds: canonicalVerifierIds,
+      data,
+      signature,
+      signedTimestamp: ts,
+      chain: resolvedChain,
+      options
+    };
+
+    const verifyResult = await ctx.callApi('/api/v1/verification', {
+      method: 'POST',
+      body: verifyBody
+    });
+
+    if (verifyResult?.status === 409 && verifyResult?.nextStep) {
+      return {
+        error: verifyResult.error,
+        message: verifyResult.message,
+        status: 409,
+        nextStep: verifyResult.nextStep
+      };
+    }
+
+    if (verifyResult?.error) return { error: verifyResult.error, message: verifyResult.message || 'Verification failed' };
+
+    const qHash = verifyResult?.data?.qHash;
+    if (qHash) log('info', 'mcp_qhash_produced', { tool: 'neus_verify' });
+
+    return {
+      success: verifyResult?.success === true,
+      status: verifyResult?.data?.status,
+      qHash
+    };
+  },
+
+  async neus_verify_or_guide(args, ctx) {
+    const {
+      walletAddress,
+      verifierIds,
+      requireAll,
+      options = {}
+    } = args || {};
+
+    if (!walletAddress || typeof walletAddress !== 'string') {
+      return { error: 'validation_error', message: 'walletAddress is required' };
+    }
+    if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
+      return { error: 'validation_error', message: 'verifierIds array with at least one ID is required' };
+    }
+
+    const idRes = resolveIdentifierToDid(String(walletAddress).trim());
+    if (idRes?.error) {
+      return { error: 'validation_error', message: idRes.error };
+    }
+    const subjectWallet = idRes.walletAddress;
+
+    const canonicalVerifierIds = verifierIds.map(v => normalizeVerifierId(v));
+    const requireAllBool = requireAll === true;
+    const threshold = requireAllBool ? canonicalVerifierIds.length : 1;
+
+    // Targeted reads: one small by-verifier page per required id (Cosmos filters at query time).
+    let proofs = [];
+    try {
+      const pages = await Promise.all(
+        canonicalVerifierIds.map((vid) =>
+          handlers.neus_proofs_get(
+            { identifier: subjectWallet, limit: 30, verifierId: normalizeVerifierId(vid) },
+            ctx
+          )
+        )
+      );
+      const byQ = new Map();
+      for (const page of pages) {
+        const list = page?.data?.proofs || [];
+        for (const p of list) {
+          const qh = p && typeof p.qHash === 'string' ? p.qHash : '';
+          if (qh && !byQ.has(qh)) byQ.set(qh, p);
+        }
+      }
+      proofs = [...byQ.values()];
+    } catch {}
+
+    const matchingProofs = proofs.filter(p => {
+      if (!p || !Array.isArray(p.verifierIds)) return false;
+      if (requireAllBool) {
+        return canonicalVerifierIds.every(id => p.verifierIds.includes(id));
+      }
+      return canonicalVerifierIds.some(id => p.verifierIds.includes(id));
+    });
+
+    const matchedCount = matchingProofs.length;
+    if (matchedCount >= threshold) {
+      return {
+        success: true,
+        action: 'already_verified',
+        eligible: true,
+        matchedCount,
+        proofs: matchingProofs.slice(0, 20),
+        message: 'Proof requirements already satisfied'
+      };
+    }
+
+    const base = 'https://neus.network/verify';
+    const params = new URLSearchParams({ verifiers: canonicalVerifierIds.join(',') });
+    const returnUrl = typeof options?.returnUrl === 'string' ? options.returnUrl.trim() : null;
+    if (returnUrl) params.set('returnUrl', returnUrl);
+    const hostedVerifyUrl = `${base}?${params.toString()}`;
+
+    let bearerHint = null;
+    if (ctx.isAuthenticated) {
+      const sw = await resolveAuthenticatedWallet(ctx);
+      const cw = normalizeWalletForMcp(subjectWallet);
+      if (sw && cw && sw === cw) {
+        bearerHint =
+          'Bearer principal wallet matches. Try neus_verify with the same walletAddress and verifierIds first for instant verifiers. If NEUS returns a browser, provider, payment, or wallet setup requirement, open hostedVerifyUrl.';
+      } else if (sw && cw && sw !== cw) {
+        bearerHint =
+          'Bearer principal differs from walletAddress. Use an access key for the matching profile or open hostedVerifyUrl.';
+      } else {
+        bearerHint =
+          'Bearer is set but the profile wallet could not be resolved. Open hostedVerifyUrl or rotate the personal access key in Profile.';
+      }
+    } else {
+      bearerHint =
+        'No Bearer on MCP. Public checks still work. For account-aware reuse, add a personal access key. Otherwise open hostedVerifyUrl when setup is missing.';
+    }
+
+    return {
+      success: false,
+      action: 'verification_required',
+      eligible: false,
+      matchedCount,
+      hostedVerifyUrl,
+      requiredVerifiers: canonicalVerifierIds,
+      bearerHint,
+      sessionHint: bearerHint,
+      next_action: 'url_handoff_or_authenticated_verify',
+      message:
+        'Proof requirements are not satisfied. Use neus_verify only when Bearer profile wallet matches walletAddress and the verifier can complete inside MCP. Otherwise open hostedVerifyUrl for the missing setup step: ' +
+        hostedVerifyUrl
+    };
+  },
+
+  /**
+   * Identity context: principal, agents, auth status.
+   * Omit identifier to resolve from the Bearer-authenticated profile (personal access key).
+   */
+  async neus_me(args, ctx) {
+    const { identifier } = args || {};
+    const uiUrl = 'https://neus.network/verify?intent=login';
+
+    if (!identifier && ctx.isAuthenticated) {
+      const meResult = await ctx.callApi('/api/v1/auth/me');
+      if (meResult?.error || meResult?.status === 401) {
+        return {
+          status: 'auth_required',
+          principal: null,
+          agents: [],
+          next_action: 'auth_required',
+          ui_url: uiUrl,
+          message: 'Bearer rejected or expired. Mint or rotate your personal access key (profile  —  Access keys) and update MCP Authorization: Bearer.'
+        };
+      }
+      const data = meResult?.data;
+      if (!data?.authenticated || !data?.did) {
+        return {
+          status: 'auth_required',
+          principal: null,
+          agents: [],
+          next_action: 'auth_required',
+          ui_url: uiUrl,
+          message: 'Bearer rejected or profile not loaded. Use a valid personal access key as Bearer, or open profile to sign in and mint a key.'
+        };
+      }
+      const did = data.did;
+      const profileResult = await ctx.callApi(`/api/v1/profile/${encodeURIComponent(did)}?includeProofsSummary=true`);
+      const associations = profileResult?.data?.associations;
+      const agents = Array.isArray(associations?.agents) ? associations.agents : [];
+      return {
+        status: 'ok',
+        principal: {
+          did: data.did,
+          handle: data.handle || data.profileSummary?.displayName || null,
+          primaryAccount: data.primaryAccount || data.address || null
+        },
+        agents,
+        next_action: null,
+        ui_url: null
+      };
+    }
+
+    if (!identifier || typeof identifier !== 'string') {
+      return {
+        status: 'auth_required',
+        principal: null,
+        agents: [],
+        next_action: ctx.isAuthenticated ? null : 'auth_required',
+        ui_url: ctx.isAuthenticated ? null : uiUrl,
+        message: ctx.isAuthenticated ? null : 'Add Authorization: Bearer with your personal access key (profile  —  Access keys), or pass identifier (wallet/DID) for public principal reads.',
+        ...(ctx.isAuthenticated ? {} : {
+          authGuidance: {
+            loginUrl: 'https://neus.network/verify?intent=login',
+            docs: 'https://docs.neus.network/mcp/auth'
+          }
+        })
+      };
+    }
+    const resolved = resolveIdentifierToDid(identifier.trim());
+    if (resolved.error) {
+      return { error: 'validation_error', message: resolved.error };
+    }
+    const profileResult = await ctx.callApi(
+      `/api/v1/profile/${encodeURIComponent(resolved.did)}?includeProofsSummary=true${ctx.isAuthenticated ? '' : '&isPublicRead=true'}`
+    );
+    if (profileResult?.error && profileResult?.status === 404) {
+      return {
+        status: 'ok',
+        principal: { did: resolved.did, handle: null, primaryAccount: resolved.walletAddress },
+        agents: [],
+        next_action: null,
+        ui_url: null
+      };
+    }
+    const data = profileResult?.data;
+    const associations = data?.associations;
+    const agents = Array.isArray(associations?.agents) ? associations.agents : [];
+    const profile = data?.profile || data;
+    const handle = profile?.metadata?.pseudonymId || profile?.displayName || null;
+    return {
+      status: 'ok',
+      principal: {
+        did: resolved.did,
+        handle: handle || null,
+        primaryAccount: resolved.walletAddress
+      },
+      agents,
+      next_action: null,
+      ui_url: null
+    };
+  },
+
+  /**
+   * Check agent readiness: agent-identity + agent-delegation.
+   * Returns linked (compat) + guided next steps with hostedVerifyUrl.
+   */
+  async neus_agent_link(args, ctx) {
+    const { agentWallet, principal } = args || {};
+    if (!agentWallet || typeof agentWallet !== 'string') {
+      return { error: 'validation_error', message: 'agentWallet is required' };
+    }
+    const trimmedAgent = normalizeWalletForMcp(agentWallet);
+
+    const resolvedPrincipal = await resolvePrincipalWallet(principal, ctx);
+    if (resolvedPrincipal?.error) return resolvedPrincipal;
+    const resolvedControllerWallet = normalizeWalletForMcp(resolvedPrincipal?.walletAddress);
+
+    // Direct lookup: use neus_proofs_get instead of gate checks.
+    // Gate checks (proofs/check) are for allowlists/campaigns; identity/delegation
+    // are single-record lookups — get the actual record and return it.
+    let identityProof = null;
+    let delegationProof = null;
+
+    try {
+      const [idPage, delPage] = await Promise.all([
+        handlers.neus_proofs_get({ identifier: trimmedAgent, limit: 25, verifierId: 'agent-identity' }, ctx),
+        handlers.neus_proofs_get({ identifier: trimmedAgent, limit: 25, verifierId: 'agent-delegation' }, ctx)
+      ]);
+      const agentIdProofs = idPage?.data?.proofs || [];
+      const agentDelProofs = delPage?.data?.proofs || [];
+      identityProof =
+        agentIdProofs.find(p => Array.isArray(p?.verifierIds) && p.verifierIds.includes('agent-identity')) || null;
+      delegationProof =
+        agentDelProofs.find(p => Array.isArray(p?.verifierIds) && p.verifierIds.includes('agent-delegation')) || null;
+    } catch {}
+
+    // Also check controller wallet for delegation proof
+    if (!delegationProof && resolvedControllerWallet) {
+      try {
+        const controllerRecords = await handlers.neus_proofs_get(
+          { identifier: resolvedControllerWallet, limit: 25, verifierId: 'agent-delegation' },
+          ctx
+        );
+        const proofs = controllerRecords?.data?.proofs || [];
+        delegationProof =
+          proofs.find(p => Array.isArray(p?.verifierIds) && p.verifierIds.includes('agent-delegation')) || null;
+      } catch {}
+    }
+
+    if (identityProof && delegationProof) {
+      return {
+        status: 'ok',
+        linked: true,
+        message: 'This agent wallet has both identity and approved access on file.',
+        principal: resolvedControllerWallet || null,
+        proofs: { identity: identityProof, delegation: delegationProof }
+      };
+    }
+
+    const hostedVerifyUrl = buildAgentHostedVerifyUrl(trimmedAgent, resolvedControllerWallet);
+    const missingVerifiers = [];
+    if (!identityProof) missingVerifiers.push('agent-identity');
+    if (!delegationProof) missingVerifiers.push('agent-delegation');
+
+    return {
+      status: 'link_required',
+      linked: false,
+      next_action: 'finish_hosted_setup',
+      nextSteps: {
+        action: 'open_hosted_verify',
+        message: resolvedControllerWallet
+          ? 'Open hostedVerifyUrl once to connect the agent wallet and approve access from your account.'
+          : 'Open hostedVerifyUrl once. Sign in to NEUS or pass the approving account so the approval step can be checked.',
+        hostedVerifyUrl,
+        requiredVerifiers: missingVerifiers.length > 0 ? missingVerifiers : ['agent-identity', 'agent-delegation'],
+        recommendedTool: 'neus_agent_create'
+      },
+      hostedVerifyUrl,
+      ...(resolvedControllerWallet ? { principal: resolvedControllerWallet } : {})
+    };
+  },
+
+  /**
+   * CREATE agent identity and delegation proofs.
+   * NO GATE CHECK - this is for creation, not verification.
+   * Returns two separate signing requests:
+   * 1. agent-identity: must be signed by agentWallet (self-attestation)
+   * 2. agent-delegation: must be signed by controllerWallet
+   *
+   * Quick Win Features:
+   * - preset: "full-access", "payments", "readonly", "automation"
+   * - agentWallet="generate": auto-generate a random EVM address
+   * - controllerWallet omitted: resolved from the active session
+   */
+  async neus_agent_create(args, ctx) {
+    const {
+      agentWallet,
+      controllerWallet,
+      agentId,
+      agentLabel,
+      agentType,
+      description,
+      capabilities,
+      permissions,
+      scope,
+      expiresAt,
+      maxSpend,
+      chain,
+      preset,
+      instructions,
+      skills,
+      services,
+      delegationInstructions,
+      delegationSkills,
+    } = args || {};
+
+    // Validate required fields
+    if (!agentId || typeof agentId !== 'string' || agentId.trim().length === 0) {
+      return { error: 'validation_error', message: 'agentId is required (1-128 chars)' };
+    }
+
+    const trimmedAgentId = agentId.trim();
+    if (trimmedAgentId.length > 128) {
+      return { error: 'validation_error', message: 'agentId must be 1-128 characters' };
+    }
+
+    // Apply preset defaults
+    const PRESETS = {
+      'full-access': {
+        capabilities: ['wallet', 'signing', 'spending', 'publishing', 'search', 'browser', 'mcp', 'webhooks', 'receipts', 'proofs', 'delegation'],
+        permissions: ['read-proofs', 'write-proofs', 'invoke-services', 'manage-delegations'],
+        scope: 'global'
+      },
+      'payments': {
+        capabilities: ['wallet', 'signing', 'spending'],
+        permissions: ['execute-payments', 'read-proofs'],
+        scope: 'payments:x402'
+      },
+      'readonly': {
+        capabilities: ['proofs', 'search'],
+        permissions: ['read-proofs'],
+        scope: 'global'
+      },
+      'automation': {
+        capabilities: ['browser', 'mcp', 'webhooks', 'proofs'],
+        permissions: ['read-proofs', 'write-proofs', 'invoke-services'],
+        scope: 'global'
+      }
+    };
+
+    const activePreset = preset && typeof preset === 'string' && PRESETS[preset.trim().toLowerCase()]
+      ? PRESETS[preset.trim().toLowerCase()]
+      : null;
+
+    // Resolve capabilities (preset or explicit)
+    const resolvedCapabilities = activePreset?.capabilities || capabilities;
+    const resolvedPermissions = activePreset?.permissions || permissions;
+    const resolvedScope = activePreset?.scope || scope;
+
+    // Resolve controller wallet
+    let resolvedControllerWallet = controllerWallet;
+    if (!resolvedControllerWallet || typeof resolvedControllerWallet !== 'string' || resolvedControllerWallet.trim() === '') {
+      if (ctx.isAuthenticated) {
+        try {
+          const meResult = await ctx.callApi('/api/v1/auth/me');
+          if (meResult?.data?.address) {
+            resolvedControllerWallet = meResult.data.address;
+          } else if (meResult?.data?.primaryAccount) {
+            resolvedControllerWallet = meResult.data.primaryAccount;
+          }
+        } catch {
+          // Session not available, will fail validation below
+        }
+      }
+    }
+
+    // Generate agent wallet if requested
+    let resolvedAgentWallet = agentWallet;
+    let generatedWallet = null;
+    if (!resolvedAgentWallet || resolvedAgentWallet.trim().toLowerCase() === 'generate') {
+      const { randomBytes } = await import('crypto');
+      const privateKeyHex = `0x${randomBytes(32).toString('hex')}`;
+      const generatedAccount = privateKeyToAccount(privateKeyHex);
+      generatedWallet = { privateKey: privateKeyHex };
+      resolvedAgentWallet = generatedAccount.address;
+    }
+
+    if (!resolvedAgentWallet || typeof resolvedAgentWallet !== 'string') {
+      return { error: 'validation_error', message: 'agentWallet is required (or use "generate" to auto-create)' };
+    }
+    if (!resolvedControllerWallet || typeof resolvedControllerWallet !== 'string') {
+      return { error: 'validation_error', message: 'Approving account wallet is required  —  sign in to NEUS or pass the wallet that will approve access (controllerWallet).' };
+    }
+
+    const trimmedAgentWallet = resolvedAgentWallet.trim();
+    const trimmedControllerWallet = resolvedControllerWallet.trim();
+
+    // Validate wallet formats
+    const agentWalletType = detectWalletType(trimmedAgentWallet);
+    const controllerWalletType = detectWalletType(trimmedControllerWallet);
+
+    if (agentWalletType === 'unknown') {
+      return { error: 'validation_error', message: 'Invalid agentWallet format. Use EVM (0x...) or Solana (base58) address.' };
+    }
+    if (controllerWalletType === 'unknown') {
+      return { error: 'validation_error', message: 'Invalid wallet address for approving account (controllerWallet). Use EVM (0x...) or Solana (base58).' };
+    }
+
+    // Resolve chain
+    const resolvedChain = resolveChain(trimmedAgentWallet, chain);
+
+    // Validate agentType
+    const allowedAgentTypes = ['ai', 'bot', 'service', 'automation', 'agent'];
+    const normalizedAgentType = agentType && allowedAgentTypes.includes(agentType.trim().toLowerCase())
+      ? agentType.trim().toLowerCase()
+      : 'ai';
+
+    // Normalize capabilities (structured object format)
+    const allowedCapabilities = new Set(['wallet', 'signing', 'spending', 'publishing', 'search', 'browser', 'mcp', 'webhooks', 'receipts', 'proofs', 'delegation']);
+    let normalizedCapabilities = null;
+    if (Array.isArray(resolvedCapabilities)) {
+      const caps = {};
+      for (const cap of resolvedCapabilities) {
+        if (typeof cap === 'string' && allowedCapabilities.has(cap.trim().toLowerCase())) {
+          caps[cap.trim().toLowerCase()] = true;
+        }
+      }
+      if (Object.keys(caps).length > 0) normalizedCapabilities = caps;
+    }
+
+    // Build agent-identity data (signed by AGENT wallet - self-attestation)
+    const normalizedDescription = description && typeof description === 'string'
+      ? description.trim().slice(0, 500)
+      : '';
+    const normalizedPermissions = Array.isArray(resolvedPermissions)
+      ? resolvedPermissions.filter(p => typeof p === 'string').slice(0, 32)
+      : [];
+    const normalizedExpiresAt = typeof expiresAt === 'number' && expiresAt > Date.now()
+      ? expiresAt
+      : null;
+
+    const trimmedMaxSpend =
+      maxSpend !== undefined && maxSpend !== null && String(maxSpend).trim() !== ''
+        ? String(maxSpend).trim()
+        : '';
+    if (trimmedMaxSpend && !/^[0-9]{1,78}$/.test(trimmedMaxSpend)) {
+      return {
+        error: 'validation_error',
+        message:
+          'maxSpend must be a whole-number string in token base units (1 — 78 digits, no decimal point). Convert a display amount with SDK toAgentDelegationMaxSpend(amount, decimalPlaces).',
+      };
+    }
+
+    let normalizedIdentityInstructions = null;
+    if (instructions !== undefined && instructions !== null && String(instructions).trim() !== '') {
+      if (typeof instructions !== 'string') {
+        return { error: 'validation_error', message: 'instructions must be a string when provided' };
+      }
+      normalizedIdentityInstructions = instructions.trim().slice(0, 16000);
+    }
+
+    const normalizedIdentitySkills = normalizeMcpAgentSkills(skills);
+    const normalizedIdentityServices = normalizeMcpAgentServices(services);
+
+    let normalizedDelegationInstructions = null;
+    if (delegationInstructions !== undefined && delegationInstructions !== null && String(delegationInstructions).trim() !== '') {
+      if (typeof delegationInstructions !== 'string') {
+        return { error: 'validation_error', message: 'delegationInstructions must be a string when provided' };
+      }
+      normalizedDelegationInstructions = delegationInstructions.trim().slice(0, 16000);
+    }
+
+    const normalizedDelegationSkills = normalizeMcpAgentSkills(delegationSkills);
+
+    const agentIdentityData = {
+      agentId: trimmedAgentId,
+      agentWallet: trimmedAgentWallet,
+      agentLabel: agentLabel && typeof agentLabel === 'string' ? agentLabel.trim().slice(0, 128) : trimmedAgentId,
+      agentType: normalizedAgentType,
+      ...(normalizedDescription ? { description: normalizedDescription } : {}),
+      ...(normalizedCapabilities ? { capabilities: normalizedCapabilities } : {}),
+      ...(normalizedIdentityInstructions ? { instructions: normalizedIdentityInstructions } : {}),
+      ...(normalizedIdentitySkills ? { skills: normalizedIdentitySkills } : {}),
+      ...(normalizedIdentityServices ? { services: normalizedIdentityServices } : {}),
+    };
+
+    // Build agent-delegation data (signed by CONTROLLER wallet)
+    const delegationData = {
+      controllerWallet: trimmedControllerWallet,
+      agentWallet: trimmedAgentWallet,
+      agentId: trimmedAgentId,
+      scope: resolvedScope && typeof resolvedScope === 'string' ? resolvedScope.trim().slice(0, 128) : 'global',
+      ...(normalizedPermissions.length > 0 ? { permissions: normalizedPermissions } : {}),
+      ...(normalizedExpiresAt ? { expiresAt: normalizedExpiresAt } : {}),
+      ...(trimmedMaxSpend ? { maxSpend: trimmedMaxSpend } : {}),
+      ...(normalizedDelegationInstructions ? { instructions: normalizedDelegationInstructions } : {}),
+      ...(normalizedDelegationSkills ? { skills: normalizedDelegationSkills } : {}),
+    };
+
+    // Get signing strings for both proofs
+    const ts = Date.now();
+
+    // Step 1: Get agent-identity signing string (agent signs for itself)
+    const identityStandardizeResult = await ctx.callApi('/api/v1/verification/standardize', {
+      method: 'POST',
+      body: {
+        walletAddress: trimmedAgentWallet,
+        verifierIds: ['agent-identity'],
+        data: agentIdentityData,
+        signedTimestamp: ts,
+        chain: resolvedChain
+      }
+    });
+
+    if (identityStandardizeResult?.error) {
+      return { error: 'standardize_error', message: identityStandardizeResult.message || 'Failed to prepare agent-identity proof' };
+    }
+
+    // Step 2: Get agent-delegation signing string (controller signs)
+    const delegationStandardizeResult = await ctx.callApi('/api/v1/verification/standardize', {
+      method: 'POST',
+      body: {
+        walletAddress: trimmedControllerWallet,
+        verifierIds: ['agent-delegation'],
+        data: delegationData,
+        signedTimestamp: ts,
+        chain: resolvedChain
+      }
+    });
+
+    if (delegationStandardizeResult?.error) {
+      return { error: 'standardize_error', message: delegationStandardizeResult.message || 'Failed to prepare agent-delegation proof' };
+    }
+
+    const identitySignerString = identityStandardizeResult?.data?.signerString;
+    const delegationSignerString = delegationStandardizeResult?.data?.signerString;
+
+    // Build hosted URL for the full flow
+    const base = 'https://neus.network/verify';
+    const hostedParams = new URLSearchParams({
+      verifiers: 'agent-identity,agent-delegation',
+      agentWallet: trimmedAgentWallet,
+      controllerWallet: trimmedControllerWallet
+    });
+    const hostedVerifyUrl = `${base}?${hostedParams.toString()}`;
+
+    log('info', 'mcp_agent_create_prepared', { agentId: trimmedAgentId, agentWallet: trimmedAgentWallet, controllerWallet: trimmedControllerWallet });
+
+    const response = {
+      status: 'signatures_required',
+      action: 'create_agent',
+      message: `Agent "${trimmedAgentId}" setup is prepared. Open hostedVerifyUrl if browser confirmation is needed, then call neus_agent_link to confirm readiness.`,
+      agent: {
+        agentId: trimmedAgentId,
+        agentWallet: trimmedAgentWallet,
+        controllerWallet: trimmedControllerWallet,
+        chain: resolvedChain,
+        preset: preset || null,
+        generatedWallet: generatedWallet ? { address: trimmedAgentWallet, privateKey: generatedWallet.privateKey, warning: 'SECURELY STORE THIS PRIVATE KEY - IT CANNOT BE RECOVERED' } : null
+      },
+      signatures: {
+        step1_agent_identity: {
+          description: 'Step 1: confirm the agent with the agent wallet.',
+          signer: trimmedAgentWallet,
+          signerString: identitySignerString,
+          signedTimestamp: ts,
+          verifierId: 'agent-identity',
+          data: agentIdentityData,
+          nextCall: {
+            tool: 'neus_verify',
+            params: {
+              walletAddress: trimmedAgentWallet,
+              verifierIds: ['agent-identity'],
+              data: agentIdentityData,
+              chain: resolvedChain,
+              signedTimestamp: ts,
+              signature: '<AGENT_SIGNATURE_HERE>'
+            }
+          }
+        },
+        step2_agent_delegation: {
+          description: 'Step 2: approve access from the account wallet.',
+          signer: trimmedControllerWallet,
+          signerString: delegationSignerString,
+          signedTimestamp: ts,
+          verifierId: 'agent-delegation',
+          data: delegationData,
+          nextCall: {
+            tool: 'neus_verify',
+            params: {
+              walletAddress: trimmedControllerWallet,
+              verifierIds: ['agent-delegation'],
+              data: delegationData,
+              chain: resolvedChain,
+              signedTimestamp: ts,
+              signature: '<CONTROLLER_SIGNATURE_HERE>'
+            }
+          }
+        }
+      },
+      executionOrder: [
+        '1. Connect the agent wallet and confirm agent details',
+        '2. From your account wallet, approve what the agent can do',
+        '3. Finish both steps (hosted flow or signatures) before treating the agent as fully set up'
+      ],
+      hostedVerifyUrl
+    };
+
+    if (generatedWallet) {
+      response.generatedWalletNotice = 'Advanced use only: this response includes the generated private key. Your runtime must store it securely and use it to sign as the agent.';
+    }
+
+    return response;
+  },
+
+  /**
+   * Get portable proof context: proof records + profile summary
+   * Composes GET /proofs/byWallet and GET /profile/:did with includeProofsSummary
+   */
+  async neus_proofs_get(args, ctx) {
+    const {
+      identifier,
+      limit: inputLimit,
+      offset: inputOffset,
+      tags: tagsArg,
+      scope,
+      agentWallet,
+      q: qArg,
+      searchQuery,
+      tagPrefix,
+      tagContains,
+      tagPrefixesAll,
+      verifierId: verifierIdArg
+    } = args || {};
+
+    if (!identifier || typeof identifier !== 'string') {
+      return { error: 'validation_error', message: 'identifier is required (wallet address or DID)' };
+    }
+
+    const trimmedId = identifier.trim();
+
+    // Resolve identifier to wallet, DID, and chain
+    let walletAddress = null;
+    let did = null;
+    let idType = 'unknown';
+    let resolvedChain = HUB_CHAIN;
+
+    if (trimmedId.startsWith('did:pkh:')) {
+      // DID format: did:pkh:namespace:reference:address (e.g., did:pkh:eip155:<hubChainId>:0x...)
+      did = trimmedId;
+      idType = 'did';
+      const parts = trimmedId.split(':');
+      if (parts.length >= 5) {
+        const namespace = parts[2];
+        if (namespace === 'eip155') {
+          walletAddress = parts.slice(4).join(':').toLowerCase();
+          resolvedChain = `eip155:${parts[3]}`;
+        } else if (namespace === 'solana') {
+          walletAddress = parts.slice(4).join(':');
+          resolvedChain = `solana:${parts[3]}`;
+        }
+      }
+    } else {
+      // Wallet address - auto-detect type
+      const walletType = detectWalletType(trimmedId);
+      if (walletType === 'evm') {
+        walletAddress = trimmedId.toLowerCase();
+        idType = 'wallet';
+        resolvedChain = HUB_CHAIN;
+        did = `did:pkh:eip155:${HUB_CHAIN_ID}:${walletAddress}`;
+      } else if (walletType === 'solana') {
+        walletAddress = trimmedId;
+        idType = 'wallet';
+        resolvedChain = SOLANA_MAINNET;
+        did = `did:pkh:solana:mainnet:${walletAddress}`;
+      } else {
+        return { error: 'validation_error', message: 'Invalid identifier format. Use EVM address (0x...), Solana address, or DID (did:pkh:...)' };
+      }
+    }
+
+    // Pagination params
+    const limit = Math.min(Math.max(1, Number(inputLimit) || 50), 100);
+    const offset = Math.max(0, Number(inputOffset) || 0);
+
+    const proofsParams = new URLSearchParams();
+    proofsParams.set('limit', String(limit));
+    proofsParams.set('offset', String(offset));
+    const tagsFromArgs = typeof tagsArg === 'string' && tagsArg.trim() ? tagsArg.trim() : '';
+    const scopeCsv = scopeToProofTagsQuery(scope);
+    const tagsMerged = tagsFromArgs || scopeCsv;
+    if (tagsMerged) {
+      const normalized = tagsMerged
+        .split(',')
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean)
+        .join(',');
+      if (normalized) proofsParams.set('tags', normalized);
+    }
+    const qText = String(searchQuery || qArg || '')
+      .trim()
+      .slice(0, 280);
+    if (qText) proofsParams.set('q', qText);
+    const verifierIdForApi = typeof verifierIdArg === 'string' ? verifierIdArg.trim().toLowerCase() : '';
+    if (verifierIdForApi) proofsParams.set('verifierId', verifierIdForApi);
+    if (!ctx.isAuthenticated) {
+      proofsParams.set('isPublicRead', '1');
+    }
+
+    const profileQs = ctx.isAuthenticated ? 'includeProofsSummary=true' : 'includeProofsSummary=true&isPublicRead=true';
+    const delegationHeaders = mcpAgentDelegationHeaders(agentWallet);
+    const [proofsResult, profileResult] = await Promise.all([
+      ctx.callApi(`/api/v1/proofs/by-wallet/${encodeURIComponent(trimmedId)}?${proofsParams.toString()}`, {
+        headers: delegationHeaders
+      }),
+      ctx.callApi(`/api/v1/profile/${encodeURIComponent(did)}?${profileQs}`)
+    ]);
+
+    // Build response
+    const response = {
+      success: true,
+      data: {
+        proofs: [],
+        profileSummary: null,
+        resolved: {
+          identifier: trimmedId,
+          walletAddress,
+          did,
+          idType,
+          chain: resolvedChain
+        },
+        pagination: {
+          limit,
+          offset,
+          totalCount: null,
+          hasMore: false,
+          nextOffset: null
+        }
+      }
+    };
+
+    // Process proofs result
+    if (proofsResult?.error) {
+      log('warn', 'mcp_proofs_error', { error: proofsResult.message || proofsResult.error });
+    } else if (proofsResult?.data) {
+      let proofList = Array.isArray(proofsResult.data.proofs) ? proofsResult.data.proofs : [];
+      const pfx = String(tagPrefix || '')
+        .trim()
+        .toLowerCase();
+      const cont = String(tagContains || '')
+        .trim()
+        .toLowerCase();
+      const allPfx = String(tagPrefixesAll || '')
+        .trim()
+        .toLowerCase();
+      if (pfx || cont || allPfx) {
+        proofList = proofList.filter((pr) => {
+          const p = unwrapApiProofRecord(pr) || pr;
+          const tags = getProofTags(p).map((t) => String(t).toLowerCase());
+          if (pfx && !tags.some((t) => t.startsWith(pfx))) return false;
+          if (cont && !tags.some((t) => t.includes(cont))) return false;
+          if (allPfx && !proofTagsMatchAllPrefixes(tags, allPfx)) return false;
+          return true;
+        });
+      }
+      response.data.proofs = proofList;
+      response.data.pagination.totalCount =
+        (typeof proofsResult.data.totalCount === 'number' && Number.isFinite(proofsResult.data.totalCount))
+          ? proofsResult.data.totalCount
+          : null;
+      response.data.pagination.hasMore = Boolean(proofsResult.data.hasMore);
+      response.data.pagination.nextOffset = proofsResult.data.nextOffset ?? null;
+      // Use resolved data from API if available
+      if (proofsResult.data.resolved) {
+        response.data.resolved.walletAddress = proofsResult.data.resolved.walletAddress || walletAddress;
+        response.data.resolved.idType = proofsResult.data.resolved.idType || idType;
+      }
+    }
+
+    // Process profile result
+    if (profileResult?.error) {
+      // Profile not found is common for new wallets; not a failure
+      if (profileResult.status !== 404) {
+        log('warn', 'mcp_profile_error', { error: profileResult.message || profileResult.error });
+      }
+    } else if (profileResult?.data) {
+      response.data.profileSummary = {
+        profile: profileResult.data.profile || null,
+        proofsSummary: profileResult.data.proofs || null,
+        linkedAccounts: profileResult.data.linkedAccounts || {}
+      };
+    }
+
+    // ========================================================================
+    // AGENT CONTEXT ENHANCEMENT (Admin AI Framework Integration)
+    // Extract agent identities and delegations from proofs
+    // ========================================================================
+    const proofs = response.data.proofs || [];
+    
+    // Extract agent identities
+    const agentIdentities = [];
+    const agentDelegations = [];
+    const agentServices = [];
+    
+    for (const proof of proofs) {
+      const verifiedVerifiers = Array.isArray(proof.verifiedVerifiers) ? proof.verifiedVerifiers : [];
+      
+      for (const vv of verifiedVerifiers) {
+        const verifierId = String(vv.verifierId || '').trim();
+        const vvData = vv.data || {};
+        
+        // Agent Identity extraction
+        if (verifierId === 'agent-identity') {
+          // Capabilities: stored as object {wallet: true, signing: false, ...}
+          // Convert to array of enabled capability keys for MCP response
+          let capabilitiesArray = [];
+          if (vvData.capabilities && typeof vvData.capabilities === 'object' && !Array.isArray(vvData.capabilities)) {
+            capabilitiesArray = Object.entries(vvData.capabilities)
+              .filter(([_, enabled]) => enabled === true)
+              .map(([key]) => key);
+          } else if (Array.isArray(vvData.capabilities)) {
+            capabilitiesArray = vvData.capabilities;
+          }
+
+          agentIdentities.push({
+            agentId: vvData.agentId || null,
+            agentWallet: vvData.agentWallet || null,
+            agentLabel: vvData.agentLabel || vvData.agentId || 'Unnamed Agent',
+            agentType: vvData.agentType || 'agent',
+            agentAccountId: vvData.agentAccountId || null,
+            agentChainRef: vvData.agentChainRef || null,
+            description: vvData.description || null,
+            capabilities: capabilitiesArray,
+            skills: Array.isArray(vvData.skills) ? vvData.skills : [],
+            instructions: vvData.instructions || null,
+            services: Array.isArray(vvData.services) ? vvData.services : []
+          });
+          
+          // Collect services
+          if (Array.isArray(vvData.services)) {
+            for (const svc of vvData.services) {
+              if (svc && typeof svc === 'object') {
+                agentServices.push({
+                  name: svc.name || 'Unknown Service',
+                  endpoint: svc.endpoint || null,
+                  version: svc.version || null
+                });
+              }
+            }
+          }
+        }
+        
+        // Agent Delegation extraction
+        if (verifierId === 'agent-delegation') {
+          const expiresAt = vvData.expiresAt || null;
+          const isExpired = expiresAt && Number.isFinite(Number(expiresAt)) && Number(expiresAt) <= Date.now();
+          
+          agentDelegations.push({
+            controllerWallet: vvData.controllerWallet || null,
+            controllerAccountId: vvData.controllerAccountId || null,
+            controllerChainRef: vvData.controllerChainRef || null,
+            agentWallet: vvData.agentWallet || null,
+            agentAccountId: vvData.agentAccountId || null,
+            agentChainRef: vvData.agentChainRef || null,
+            agentId: vvData.agentId || null,
+            scope: vvData.scope || 'global',
+            permissions: Array.isArray(vvData.permissions) ? vvData.permissions : [],
+            maxSpend: vvData.maxSpend || null,
+            expiresAt: expiresAt || null,
+            isExpired: Boolean(isExpired),
+            allowedPaymentTypes: Array.isArray(vvData.allowedPaymentTypes) ? vvData.allowedPaymentTypes : [],
+            receiptDisclosure: vvData.receiptDisclosure || null,
+            instructions: vvData.instructions || null,
+            skills: Array.isArray(vvData.skills) ? vvData.skills : []
+          });
+        }
+      }
+    }
+    
+    // Calculate context pack summary
+    const activeDelegations = agentDelegations.filter(d => !d.isExpired).length;
+    const allCapabilities = [];
+    const allSkills = [];
+    const seenCapabilityKeys = new Set();
+    const seenSkillIds = new Set();
+
+    for (const identity of agentIdentities) {
+      // Capabilities are already arrays of strings
+      if (Array.isArray(identity.capabilities)) {
+        for (const cap of identity.capabilities) {
+          const key = String(cap).toLowerCase();
+          if (!seenCapabilityKeys.has(key)) {
+            seenCapabilityKeys.add(key);
+            allCapabilities.push(cap);
+          }
+        }
+      }
+      // Skills are objects {id, label, version, ...} - dedupe by id
+      if (Array.isArray(identity.skills)) {
+        for (const skill of identity.skills) {
+          const skillId = (skill && typeof skill === 'object' && skill.id) ? String(skill.id) : null;
+          if (skillId && !seenSkillIds.has(skillId)) {
+            seenSkillIds.add(skillId);
+            allSkills.push(skill);
+          }
+        }
+      }
+    }
+    
+    // Add agent context to response
+    response.data.agentContext = {
+      identities: agentIdentities,
+      delegations: agentDelegations,
+      services: agentServices
+    };
+    
+    response.data.contextPack = {
+      identityCount: agentIdentities.length,
+      delegationCount: agentDelegations.length,
+      activeDelegations: activeDelegations,
+      capabilitiesSummary: allCapabilities.slice(0, 20), // Top 20 unique capabilities
+      skillsSummary: allSkills.slice(0, 30) // Top 30 unique skills
+    };
+
+    return response;
+  },
+
+  async zeus_url_fetch(args) {
+    const raw = String(args?.url || '').trim();
+    if (!raw) return { error: 'validation_error', message: 'url is required' };
+    let url;
+    try {
+      url = new URL(raw);
+    } catch {
+      return { error: 'validation_error', message: 'Invalid URL' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return { error: 'validation_error', message: 'Only http and https URLs are allowed' };
+    }
+    if (isBlockedZeusFetchHost(url.hostname)) {
+      return { error: 'blocked_host', message: 'This host is blocked (local/private/metadata addresses).' };
+    }
+    const maxChars = Math.min(400000, Math.max(5000, Number(args?.maxChars) || 120000));
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 22000);
+    try {
+      const response = await fetch(url.toString(), {
+        method: 'GET',
+        redirect: 'follow',
+        signal: controller.signal,
+        headers: {
+          accept: 'text/html, text/plain, application/json;q=0.8, */*;q=0.2',
+          'user-agent': 'NEUS-Zeus-MCP/1.0'
+        }
+      });
+      const contentType = response.headers.get('content-type') || '';
+      const body = await response.text();
+      return {
+        success: response.ok,
+        status: response.status,
+        url: response.url,
+        contentType: contentType.split(';')[0] || 'unknown',
+        truncated: body.length > maxChars,
+        body: body.slice(0, maxChars)
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  },
+
+  async zeus_execute_javascript(args) {
+    try {
+      const { value, logs } = await runZeusSandbox(String(args?.script || ''), args?.input, args?.timeoutMs);
+      return { success: true, output: value, logs };
+    } catch (error) {
+      return { error: 'javascript_execution_error', message: String(error?.message || error || 'Execution failed') };
+    }
+  },
+
+  async execute_javascript_code(args) {
+    return handlers.zeus_execute_javascript(args);
+  },
+
+  async zeus_skill_tools_list(args, ctx) {
+    const identifier = String(args?.identifier || '').trim() || (await resolveAuthenticatedWallet(ctx));
+    if (!identifier) return { error: 'validation_error', message: 'identifier or Bearer profile wallet required' };
+    const limit = Math.min(Math.max(1, Number(args?.limit) || 100), 250);
+    const offset = Math.max(0, Number(args?.offset) || 0);
+    const query = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      tags: 'tool,skill,agent:tool,agent:skill'
+    });
+    if (!ctx.isAuthenticated) query.set('isPublicRead', '1');
+    const result = await ctx.callApi(`/api/v1/proofs/by-wallet/${encodeURIComponent(identifier)}?${query.toString()}`, {
+      headers: mcpAgentDelegationHeaders(args?.agentWallet)
+    });
+    const proofs = Array.isArray(result?.data?.proofs)
+      ? result.data.proofs
+      : Array.isArray(result?.proofs)
+        ? result.proofs
+        : Array.isArray(result?.data)
+          ? result.data
+          : [];
+    return {
+      success: result?.error ? false : true,
+      items: proofs.map((proof) => ({
+        qHash: getProofQHash(proof),
+        title: getProofTitle(proof),
+        tags: getProofTags(proof)
+      })).filter((item) => item.qHash),
+      rawCount: proofs.length
+    };
+  },
+
+  async zeus_skill_tool_execute(args, ctx) {
+    const qHash = String(args?.qHash || '').trim();
+    if (!/^0x[a-fA-F0-9]{64}$/.test(qHash)) return { error: 'validation_error', message: 'valid qHash required' };
+    const proof = await ctx.callApi(`/api/v1/proofs/${encodeURIComponent(qHash)}`);
+    if (proof?.error) return proof;
+    const content = getProofContentText(proof);
+    const parsed = parseSkillToolProofSections(content);
+    if (!parsed.separatorFound || !parsed.script) {
+      return {
+        error: 'invalid_tool_proof',
+        message: 'Tool proof must contain markdown summary, separator line -----, then JavaScript.'
+      };
+    }
+    try {
+      const { value, logs } = await runZeusSandbox(parsed.script, args?.input, args?.timeoutMs);
+      return { success: true, qHash, summaryMarkdown: parsed.summaryMarkdown, output: value, logs };
+    } catch (error) {
+      return { error: 'javascript_execution_error', message: String(error?.message || error || 'Execution failed') };
+    }
+  },
+
+  async zeus_session_receipt_create(args, ctx) {
+    // Skip receipt creation in local dev to avoid persistent storage clutter / stuck execution.
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
+      return { success: true, skipped: true, note: 'Skipped in dev ? receipts not created on localhost.' };
+    }
+    const walletAddress = await resolveReceiptWallet(args, ctx);
+    const content = String(args?.content || '').trim();
+    if (!walletAddress || !content) {
+      return { error: 'validation_error', message: 'walletAddress/Bearer profile wallet and content required' };
+    }
+    const visibility = 'private';
+    const extraTags = normalizeStringArray(args?.tags).filter((t) => !/^receipt:/i.test(t));
+    const tags = Array.from(new Set([...extraTags, 'receipt:chat']));
+    const title = String(args?.title || '').trim() || `Zeus session receipt  —  ${new Date().toISOString().slice(0, 19).replace('T', ' ')} UTC`;
+    const body = {
+      walletAddress,
+      verifierIds: ['ownership-basic'],
+      data: {
+        owner: walletAddress,
+        content: content.slice(0, 48000),
+        contentType: 'text/plain'
+      },
+      options: {
+        ...proofOptionsForVisibility(visibility),
+        storeOriginalContent: true,
+        meta: { title, visibility, tags }
+      },
+      meta: { title, visibility, tags }
+    };
+    const result = await ctx.callApi('/api/v1/verification', { method: 'POST', body });
+    return { success: !result?.error, receipt: result, qHash: result?.data?.qHash || result?.qHash || null };
+  },
+
+  async zeus_session_receipt_append(args, ctx) {
+    const qHash = String(args?.qHash || '').trim();
+    const appendContent = String(args?.appendContent || '').trim();
+    if (!/^0x[a-fA-F0-9]{64}$/.test(qHash) || !appendContent) {
+      return { error: 'validation_error', message: 'qHash and appendContent required' };
+    }
+    const existing = await ctx.callApi(`/api/v1/proofs/${encodeURIComponent(qHash)}`);
+    if (existing?.error) return existing;
+    const previous = getProofContentText(existing);
+    const title = String(args?.title || existing?.data?.meta?.title || existing?.meta?.title || 'Zeus session receipt').trim();
+    const content = [previous, `\n\n---\n\n## Appended ${new Date().toISOString()}\n\n${appendContent}`].join('').trim();
+    const created = await handlers.zeus_session_receipt_create({
+      ...args,
+      title,
+      content,
+      tags: [`supersedes:${qHash.toLowerCase()}`],
+      asPrivate: args?.asPrivate
+    }, ctx);
+    return { ...created, previousQHash: qHash, action: 'append_created_superseding_receipt' };
+  },
+
+  async list_tools(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'tool,skill,agent:tool,agent:skill');
+  },
+
+  async list_all_available_tools(_args, ctx) {
+    return ctx.exposedToolNames || [...PUBLIC_MCP_TOOL_NAMES_ORDERED];
+  },
+
+  async list_memories(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'memory');
+  },
+
+  async list_research(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'research');
+  },
+
+  async list_instructions(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'instruction,instructions');
+  },
+
+  async list_rules(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'rule,rules');
+  },
+
+  async list_mcps(args, ctx) {
+    return fetchProofTitleIdMap(ctx, args, 'mcp');
+  },
+
+  async get_tool(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'tool');
+  },
+
+  async get_skill(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'skill');
+  },
+
+  async get_memory(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'memory');
+  },
+
+  async get_instruction(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'instruction');
+  },
+
+  async get_rule(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'rule');
+  },
+
+  async get_research(args, ctx) {
+    return getCategorizedProofByHash(args, ctx, 'research');
+  },
+
+  async append_Content_to_memory(args, ctx) {
+    const qHash = normalizeQHashInput(args?.qHash);
+    const append = String(args?.appendContent || args?.content || '').trim();
+    if (!qHash) return { error: 'validation_error', message: 'qHash is required' };
+    if (!append) return { error: 'validation_error', message: 'appendContent or content is required' };
+    const raw = await ctx.callApi(`/api/v1/proofs/${encodeURIComponent(qHash)}`);
+    if (raw?.error) return raw;
+    const un = unwrapApiProofRecord(raw) || raw;
+    if (!proofMatchesCategory(un, 'memory') && !proofMatchesCategory(raw, 'memory')) {
+      return { error: 'validation_error', message: 'Target proof must be tagged as memory' };
+    }
+    const previous = getProofContentText(un);
+    const wallet = await resolveReceiptWallet(args, ctx);
+    if (!wallet) return { error: 'validation_error', message: 'walletAddress or authenticated profile wallet is required' };
+    const newContent = [previous, append].filter(Boolean).join('\n\n').trim();
+    const baseTitle = getProofTitle(un);
+    const title = `Memory (append)${baseTitle && baseTitle !== 'Proof' ? `  —  ${baseTitle}` : ''}`.trim();
+    const supTag = `supersedes:${qHash.toLowerCase()}`;
+    const dense = buildZeusProofIndexTags({
+      category: 'memory',
+      title,
+      content: newContent.slice(0, 28000),
+      facetKeys: normalizeStringArray(args?.indexFacetKeys)
+    });
+    const tags = Array.from(new Set(['memory', supTag, 'zappend', ...dense]));
+    const body = {
+      walletAddress: wallet,
+      verifierIds: ['ownership-basic'],
+      data: {
+        owner: wallet,
+        content: newContent.slice(0, 48000),
+        contentType: 'text/plain'
+      },
+      options: {
+        ...proofOptionsForVisibility(args?.asPrivate === true ? 'private' : 'unlisted'),
+        storeOriginalContent: true,
+        meta: { title, visibility: args?.asPrivate === true ? 'private' : 'unlisted', tags }
+      },
+      meta: { title, visibility: args?.asPrivate === true ? 'private' : 'unlisted', tags }
+    };
+    const result = await ctx.callApi('/api/v1/verification', { method: 'POST', body });
+    return { success: !result?.error, previousQHash: qHash, newProof: result, qHash: result?.data?.qHash || result?.qHash || null };
+  },
+
+  async delete_revoke_memory(args, ctx) {
+    const qHash = normalizeQHashInput(args?.qHash);
+    if (!qHash) return { error: 'validation_error', message: 'qHash is required' };
+    const raw = await ctx.callApi(`/api/v1/proofs/${encodeURIComponent(qHash)}`);
+    if (raw?.error) return raw;
+    const un = unwrapApiProofRecord(raw) || raw;
+    if (!proofMatchesCategory(un, 'memory') && !proofMatchesCategory(raw, 'memory')) {
+      return { error: 'validation_error', message: 'Target proof must be tagged as memory' };
+    }
+    const wallet = await resolvePrincipalWallet(
+      args?.walletAddress && typeof args.walletAddress === 'string' ? String(args.walletAddress) : null,
+      ctx
+    );
+    if (wallet?.error) return wallet;
+    if (!wallet?.walletAddress) {
+      return { error: 'validation_error', message: 'wallet or Bearer session required to revoke' };
+    }
+    return ctx.callApi(`/api/v1/proofs/revoke-self/${encodeURIComponent(qHash)}`, {
+      method: 'POST',
+      body: { walletAddress: wallet.walletAddress }
+    });
+  },
+
+  async list_agents(args, ctx) {
+    const ident = String(args?.identifier || '').trim() || (await resolveAuthenticatedWallet(ctx));
+    if (!ident) return { error: 'validation_error', message: 'identifier or Bearer profile wallet is required' };
+    return handlers.neus_proofs_get(
+      {
+        identifier: ident,
+        limit: Math.min(Math.max(1, Number(args?.limit) || 120), 200),
+        offset: 0,
+        agentWallet: args?.agentWallet
+      },
+      ctx
+    ).then((r) => {
+      if (r?.error) return r;
+      const ag = r?.data?.agentContext;
+      if (!ag) return { success: true, identities: [], delegations: [], services: [] };
+      return {
+        success: true,
+        identities: ag.identities || [],
+        delegations: ag.delegations || [],
+        services: ag.services || [],
+        contextPack: r.data?.contextPack || null
+      };
+    });
+  },
+
+  async execute_agent_command(args, ctx) {
+    if (!NEUS_MCP_INFERENCE_KEY) {
+      return {
+        error: 'configuration_error',
+        message:
+          'Set NEUS_MCP_INFERENCE_API_KEY or OPENROUTER_API_KEY in the MCP server environment, or use Zeus in the web app for full agent chat (session cookie).'
+      };
+    }
+    const prompt = String(args?.prompt || '').trim();
+    if (!prompt) return { error: 'validation_error', message: 'prompt is required' };
+    const requestId = randomUUID();
+    const ac = new AbortController();
+    agentInferenceJobs.set(requestId, { controller: ac, startedAt: Date.now() });
+    const model = String(args?.model || NEUS_MCP_INFERENCE_MODEL).trim();
+    const temperature = Math.min(2, Math.max(0, Number.isFinite(Number(args?.temperature)) ? Number(args.temperature) : 0.3));
+    const agentW = String(args?.agentWallet || '').trim();
+    const agentId = String(args?.agentId || '').trim();
+    const baseSystem =
+      String(args?.systemPrompt || '').trim() ||
+      `You are a delegated NEUS agent task runner. Be concise. User wallet context may be available via the caller.\n${
+        agentW ? `Agent wallet: ${agentW}.\n` : ''
+      }${agentId ? `Agent id: ${agentId}.\n` : ''}`;
+    const body = {
+      model,
+      temperature,
+      messages: [
+        { role: 'system', content: baseSystem },
+        { role: 'user', content: prompt }
+      ]
+    };
+    const url = `${NEUS_MCP_INFERENCE_BASE_URL}/chat/completions`;
+    const t = setTimeout(() => ac.abort(), 120000);
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        signal: ac.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${NEUS_MCP_INFERENCE_KEY}`,
+          Referer: MCP_PUBLIC_URL,
+          'X-Title': 'NEUS-MCP-execute_agent_command'
+        },
+        body: JSON.stringify(body)
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        return {
+          error: 'inference_error',
+          status: res.status,
+          message: data?.error?.message || data?.message || 'Inference request failed',
+          requestId
+        };
+      }
+      const text =
+        (Array.isArray(data?.choices) && data.choices[0] && (data.choices[0].message?.content || data.choices[0].text)) ||
+        (typeof data?.output_text === 'string' ? data.output_text : null) ||
+        '';
+      return {
+        success: true,
+        requestId,
+        model,
+        response: typeof text === 'string' ? text : String(text),
+        note: 'OpenAI-compatible /chat/completions. To cancel mid-flight, call stop_agent_processing with requestId (same MCP process).'
+      };
+    } catch (e) {
+      if (e?.name === 'AbortError') {
+        return { error: 'aborted', requestId, message: 'Request aborted' };
+      }
+      return { error: 'inference_error', message: String(e?.message || e), requestId };
+    } finally {
+      clearTimeout(t);
+      agentInferenceJobs.delete(requestId);
+    }
+  },
+
+  async stop_agent_processing(args) {
+    const id = String(args?.requestId || '').trim();
+    if (!id) return { error: 'validation_error', message: 'requestId is required' };
+    const job = agentInferenceJobs.get(id);
+    if (!job) return { success: false, message: 'No active job with that requestId' };
+    try {
+      job.controller.abort();
+    } catch { /* */ }
+    agentInferenceJobs.delete(id);
+    return { success: true, stopped: true, requestId: id };
+  },
+
+  async encrypt_text(args) {
+    const text = String(args?.text || '');
+    if (!text.trim()) return { error: 'validation_error', message: 'text is required' };
+    return {
+      success: true,
+      encrypted: wrapEncryptedPayload(encryptPlaintext(text)),
+      note: 'Store and transmit this value as-is. Decrypt only when plaintext is required for immediate execution.'
+    };
+  },
+
+  async decrypt_text(args) {
+    const raw = String(args?.text || '').trim();
+    if (!raw) return { error: 'validation_error', message: 'text is required' };
+    const payload =
+      raw.startsWith(ENCRYPT_TAG_OPEN) && raw.endsWith(ENCRYPT_TAG_CLOSE)
+        ? raw.slice(ENCRYPT_TAG_OPEN.length, raw.length - ENCRYPT_TAG_CLOSE.length).trim()
+        : raw;
+    try {
+      return {
+        success: true,
+        plaintext: decryptPayload(payload),
+        note: 'Plaintext was decrypted for immediate-use execution context.'
+      };
+    } catch (error) {
+      return {
+        error: 'validation_error',
+        message: `Failed to decrypt payload: ${String(error?.message || error)}`
+      };
+    }
+  },
+
+  async mcp_connection_create(args) {
+    const n = normalizeMcpConnectionEntry(args);
+    if (!n) return { error: 'validation_error', message: 'Valid id, type (streamableHttp|stdio), and url or command are required' };
+      return { success: true, connection: n, hint: 'Hosted MCP returns normalized config  —  merge according to your client — s documented MCP wiring.' };
+  },
+
+  async mcp_connection_modify(args) {
+    const conn = normalizeMcpConnectionEntry(args?.connection);
+    if (!conn) return { error: 'validation_error', message: 'connection object with id, type, and url|command is required' };
+    const list = Array.isArray(args?.mcpConnections) ? args.mcpConnections : [];
+    const norm = list.map((x) => normalizeMcpConnectionEntry(x)).filter((c) => c != null);
+    const next = norm.some((c) => c.id === conn.id) ? norm.map((c) => (c.id === conn.id ? conn : c)) : [...norm, conn];
+    return { success: true, mcpConnections: next, action: 'upsert' };
+  },
+
+  async mcp_connection_delete(args) {
+    const id = String(args?.id || '').trim();
+    if (!id) return { error: 'validation_error', message: 'id is required' };
+    if (id.toLowerCase() === 'neus-mcp' || id.toLowerCase() === 'neus') {
+      return { error: 'validation_error', message: 'The default NEUS MCP connection id cannot be deleted via this tool.' };
+    }
+    const list = Array.isArray(args?.mcpConnections) ? args.mcpConnections : null;
+    if (!list) {
+      return { success: true, mcpConnections: [], deleted: id, note: 'No mcpConnections list passed  —  pass your current MCP connection list when your client expects it.' };
+    }
+    const next = list
+      .map((x) => normalizeMcpConnectionEntry(x))
+      .filter((c) => c != null && c.id !== id);
+    return { success: true, mcpConnections: next, deleted: id };
+  },
+
+  // ============================================================================
+  // NEUS CONTEXT  —  Single entry point for all NEUS context
+  // ============================================================================
+
+  async neus_context(_args, ctx) {
+    const verifiersResult = await ctx.callApi('/api/v1/verification/verifiers');
+    return buildPublicNeusContextPayload(ctx, verifiersResult);
+  }
+};
+
+/**
+ * Extended/internal tools follow MCP_EXTENDED_TOOLS_POLICY.
+ * Defaults to off everywhere. Only `admin_wallet` can expose them, and only for a Bearer
+ * profile wallet listed in MCP_ADMIN_ADDRESSES / ADMIN_ADDRESSES.
+ */
+async function resolveMcpExtendedToolsExposure(sessionBearerToken) {
+  const policy = mcp.mcpExtendedToolsPolicy;
+  if (policy === 'off') return false;
+  const ctx = createSessionCtx(sessionBearerToken, [...PUBLIC_MCP_TOOL_NAMES_ORDERED]);
+  const wallet = await resolveAuthenticatedWallet(ctx);
+  if (!wallet) return false;
+  return mcp.mcpAdminWalletSet.has(wallet.toLowerCase());
+}
+
+// ============================================================================
+// MCP SERVER SETUP
+// ============================================================================
+
+/**
+ * @param {string} name
+ * @param {Record<string, unknown>} args
+ * @param {ReturnType<typeof createSessionCtx>} sessionCtx
+ */
+async function runNeusToolCall(name, args, sessionCtx) {
+  const handler = handlers[name];
+  if (!handler) {
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ error: 'unknown_tool', message: `Unknown tool: ${name}` }) }],
+      isError: true
+    };
+  }
+
+  try {
+    const decryptedArgs = decryptArgsDeep(args || {});
+    const result = await handler(decryptedArgs, sessionCtx);
+    const protectedResult = encryptSensitiveDeep(result);
+    const isError = result?.error !== undefined;
+
+    let statusCode = null;
+    if (result?.status) {
+      statusCode = Number(result.status);
+    } else if (result?.error && typeof result.error === 'object' && result.error.statusCode) {
+      statusCode = Number(result.error.statusCode);
+    }
+
+    if (protectedResult?.elicitation?.required) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(protectedResult, null, 2)
+        }],
+        isError: false,
+        meta: { elicitationRequired: true }
+      };
+    }
+
+    if (statusCode && statusCode >= 400) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: protectedResult?.error || 'api_error',
+            message: protectedResult?.message || `Request failed (${statusCode})`,
+            statusCode,
+            ...(protectedResult?.nextStep ? { nextStep: protectedResult.nextStep } : {}),
+            ...(protectedResult?.remediation ? { remediation: protectedResult.remediation } : {}),
+            ...(protectedResult?.hostedCheckoutUrl ? { hostedCheckoutUrl: protectedResult.hostedCheckoutUrl } : {})
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(protectedResult, null, 2) }],
+      isError
+    };
+  } catch (err) {
+    const statusCode = err?.statusCode || (err?.status >= 400 && err?.status < 600 ? err.status : 500);
+    const is4xx = statusCode >= 400 && statusCode < 500;
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'handler_error',
+          message: err.message,
+          errorType: is4xx ? 'client_error' : 'server_error',
+          statusCode
+        })
+      }],
+      isError: true
+    };
+  }
+}
+
+/**
+ * Factory to create a new MCP Server instance with request-scoped auth.
+ * Each client session gets its own McpServer instance and session context.
+ * @param {string|null} sessionBearerToken - Per-session bearer token (from client HTTP header)
+ * @param {{ exposeExtendedTools?: boolean }} [options]
+ * @returns {McpServer}
+ */
+function createNeusServer(sessionBearerToken = null, options = {}) {
+  const exposeExtendedTools = options.exposeExtendedTools === true;
+  const exposedToolNames = exposeExtendedTools
+    ? TOOLS.map((t) => t.name)
+    : [...PUBLIC_MCP_TOOL_NAMES_ORDERED];
+  const sessionCtx = createSessionCtx(sessionBearerToken, exposedToolNames);
+
+  const srv = new McpServer(
+    { name: 'neus-mcp', version: '1.0.0' },
+    {
+      capabilities: {
+        tools: {},
+        elicitation: {}
+      },
+      instructions: `${buildMcpAssistantInstructions(exposeExtendedTools)}
+
+Identifier formats:
+- EVM wallet: 0x... (40 hex chars)
+- Solana wallet: base58 (32-44 chars)
+- DID: did:pkh:eip155:<hubChainId>:0x...`
+    }
+  );
+
+  const toolsToRegister = toolDefinitionsForExposure(exposeExtendedTools);
+
+  for (const tool of toolsToRegister) {
+    const zodInput = TOOL_ZOD_INPUT[tool.name];
+    if (!zodInput) {
+      throw new Error(`Missing TOOL_ZOD_INPUT for ${tool.name}`);
+    }
+    srv.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: zodInput
+      },
+      async (args) => runNeusToolCall(tool.name, args, sessionCtx)
+    );
+  }
+
+  return srv;
+}
+
+function toolDefinitionsForExposure(exposeExtendedTools = false) {
+  return exposeExtendedTools ? TOOLS : TOOLS.filter((t) => PUBLIC_MCP_TOOL_SET.has(t.name));
+}
+
+function toolNamesForExposure(exposeExtendedTools = false) {
+  return toolDefinitionsForExposure(exposeExtendedTools).map((t) => t.name);
+}
+
+// ============================================================================
+// SERVER STARTUP
+// ============================================================================
+
+async function main() {
+  // Default to HTTP (open hosted mode). Set MCP_TRANSPORT=stdio for local/CLI use.
+  const transportMode = mcp.mcpTransport;
+
+  if (transportMode === 'http') {
+    // MCP_AUTH_TOKEN: optional shared secret for HTTP MCP when MCP_REQUIRE_AUTH=true (self-hosted). Never forwarded to the NEUS API.
+    const authToken = mcp.mcpAuthToken;
+    const requireAuthEnabled = mcp.mcpRequireAuth;
+    // Hosted default: OPEN (no MCP session secret). API enforces signer + payment + rate limits.
+    // Private mode: set MCP_REQUIRE_AUTH=true and MCP_AUTH_TOKEN=<token>.
+
+    const allowedOrigins = mcp.mcpAllowedOrigins;
+    const allowedHosts = mcp.mcpAllowedHosts;
+    const enableDnsRebindingProtection = allowedOrigins.length > 0 || allowedHosts.length > 0;
+
+    const extractNeusSessionToken = (req) => {
+      const neusSession = String(req?.headers?.['x-neus-session'] || '').trim();
+      if (neusSession) return neusSession;
+      if (!requireAuthEnabled) {
+        const authHeader = String(req?.headers?.authorization || '').trim();
+        if (authHeader.startsWith('Bearer ')) return authHeader.slice('Bearer '.length).trim();
+      }
+      return null;
+    };
+
+    const createStatelessTransport = async (req) => {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        allowedOrigins,
+        allowedHosts,
+        enableDnsRebindingProtection
+      });
+      const neusToken = extractNeusSessionToken(req);
+      const exposeExtended = await resolveMcpExtendedToolsExposure(neusToken);
+      const srv = createNeusServer(neusToken, { exposeExtendedTools: exposeExtended });
+      await srv.connect(transport);
+      log('info', 'mcp_stateless_transport_created', {
+        authenticated: !!neusToken,
+        exposeExtendedTools: exposeExtended,
+        extendedToolsPolicy: mcp.mcpExtendedToolsPolicy
+      });
+      return { server: srv, transport };
+    };
+
+    const port = mcp.port;
+    const host = mcp.host;
+    const mcpPath = '/mcp';
+    const isMcpPath = (pathname) => pathname === mcpPath || pathname === '/';
+
+    const safeEqual = (a, b) => {
+      try {
+        const aa = Buffer.from(String(a), 'utf8');
+        const bb = Buffer.from(String(b), 'utf8');
+        if (aa.length !== bb.length) return false;
+        return timingSafeEqual(aa, bb);
+      } catch {
+        return false;
+      }
+    };
+    const setErrorCorsHeaders = (req, res) => {
+      const reqOrigin = String(req?.headers?.origin || '').trim();
+      const origin = allowedOrigins.length === 0
+        ? '*'
+        : (reqOrigin && allowedOrigins.includes(reqOrigin) ? reqOrigin : allowedOrigins[0]);
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Access-Control-Allow-Methods', 'GET,POST,DELETE,OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-Neus-Session,mcp-protocol-version,Mcp-Session-Id');
+      res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+      if (origin !== '*') {
+        const existingVary = String(res.getHeader('Vary') || '').trim();
+        res.setHeader('Vary', existingVary ? `${existingVary}, Origin` : 'Origin');
+      }
+    };
+    const writeErrorJson = (req, res, statusCode, payload) => {
+      setErrorCorsHeaders(req, res);
+      res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    };
+
+    const requireAuth = (req, res) => {
+      if (!requireAuthEnabled) return true; // Open mode: no auth required
+      if (!authToken) {
+        writeErrorJson(req, res, 500, { error: 'misconfigured_auth', message: 'MCP_REQUIRE_AUTH=true but MCP_AUTH_TOKEN is empty' });
+        return false;
+      }
+      const header = String(req.headers.authorization || '').trim();
+      const token = header.startsWith('Bearer ') ? header.slice('Bearer '.length).trim() : '';
+      if (!token || !safeEqual(token, authToken)) {
+        writeErrorJson(req, res, 401, { error: 'unauthorized' });
+        return false;
+      }
+      return true;
+    };
+
+    const requireProtocolHeader = (req, res) => {
+      // DELETE terminate requests from some clients omit protocol header.
+      if (String(req?.method || '').toUpperCase() === 'DELETE') return true;
+      let v = req.headers['mcp-protocol-version'] || req.headers['MCP-Protocol-Version'];
+      if (!v) {
+        v = MCP_PROTOCOL_VERSION;
+        req.headers['mcp-protocol-version'] = v;
+      }
+      return true;
+    };
+
+    const mcpWellKnownPath = '/.well-known/mcp.json';
+    const serverCardPath = '/.well-known/mcp/server-card.json';
+    const getCorsOrigin = (req) => {
+      const reqOrigin = String(req?.headers?.origin || '').trim();
+      if (allowedOrigins.length === 0) return '*';
+      if (reqOrigin && allowedOrigins.includes(reqOrigin)) return reqOrigin;
+      return allowedOrigins[0];
+    };
+    const setCorsHeaders = (req, res) => {
+      const origin = getCorsOrigin(req);
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Access-Control-Allow-Methods', 'GET,POST,DELETE,OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-Neus-Session,mcp-protocol-version,Mcp-Session-Id');
+      res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+      res.setHeader('Access-Control-Max-Age', '86400');
+      if (origin !== '*') {
+        const existingVary = String(res.getHeader('Vary') || '').trim();
+        res.setHeader('Vary', existingVary ? `${existingVary}, Origin` : 'Origin');
+      }
+    };
+    const writeJson = (req, res, statusCode, payload) => {
+      setCorsHeaders(req, res);
+      res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    };
+
+    const httpServer = createServer(async (req, res) => {
+      // Generate request ID for logging
+      const requestId = randomUUID();
+      req.requestId = requestId;
+      
+      log('info', 'mcp_request_start', {
+        requestId,
+        method: req?.method,
+        url: req?.url
+      });
+
+      const mcpRequestStart = Date.now();
+      res.on('finish', () => {
+        const durationMs = Date.now() - mcpRequestStart;
+        log('info', 'neus.mcp.request.completed', {
+          requestId,
+          method: req.method,
+          path: req._mcpPathname || null,
+          statusCode: res.statusCode,
+          durationMs,
+          toolName: req._mcpParsedBody?.params?.name ?? null,
+          agentId: req.agentId ?? null,
+          errorCode: req.errorCode ?? null,
+          service: 'protocol-mcp',
+          environment: process.env.NODE_ENV || 'production'
+        });
+      });
+
+      try {
+        if (!req || !res) return;
+        if (!req.url) {
+          return writeJson(req, res, 400, { error: 'missing_url', requestId });
+        }
+
+        const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+        req._mcpPathname = url.pathname;
+        if (req.method === 'OPTIONS' && (isMcpPath(url.pathname) || url.pathname === '/health' || url.pathname === '/health/ready' || url.pathname === mcpWellKnownPath || url.pathname === serverCardPath)) {
+          setCorsHeaders(req, res);
+          res.writeHead(204);
+          return res.end();
+        }
+        
+        // Health check endpoint (no auth required)
+        if (url.pathname === '/health') {
+          return writeJson(req, res, 200, {
+            status: 'ok', 
+            timestamp: Date.now(),
+            requestId 
+          });
+        }
+
+        // Readiness endpoint (dependency-aware)
+        if (url.pathname === '/health/ready') {
+          const readyResult = await callNeusApi('/api/v1/health', { maxRetries: 0 });
+          if (readyResult?.error) {
+            return writeJson(req, res, 503, {
+              status: 'degraded',
+              ready: false,
+              dependency: 'api.neus.network',
+              reason: readyResult.message || readyResult.error,
+              requestId
+            });
+          }
+          return writeJson(req, res, 200, {
+            status: 'ok',
+            ready: true,
+            dependency: 'api.neus.network',
+            requestId
+          });
+        }
+
+        if (url.pathname === mcpWellKnownPath) {
+          return writeJson(req, res, 200, {
+            version: '1.0',
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            serverInfo: { name: 'neus-mcp', title: 'NEUS MCP', version: '1.0.0' },
+            description:
+              'NEUS hosted MCP: verifiers, proofs, verify flows, agents. Always call neus_context first.',
+            transport: 'streamable-http',
+            url: `${MCP_PUBLIC_URL}${mcpPath}`,
+            capabilities: { tools: true, elicitation: true },
+            tools: toolsForPublicDiscovery(),
+            documentationUrl: 'https://docs.neus.network/mcp/overview',
+            iconUrl: 'https://neus.network/images/neus-brand-pack/neus-mark-128.png'
+          });
+        }
+
+        if (url.pathname === serverCardPath) {
+          return writeJson(req, res, 200, {
+            name: 'neus-mcp',
+            title: 'NEUS MCP',
+            version: '1.0.0',
+            description:
+              'NEUS hosted MCP: verifiers, proofs, verify flows, agents. Always call neus_context first.',
+            transport: 'streamable-http',
+            url: `${MCP_PUBLIC_URL}${mcpPath}`,
+            documentationUrl: 'https://docs.neus.network/mcp/overview',
+            iconUrl: 'https://neus.network/images/neus-brand-pack/neus-mark-128.png',
+            capabilities: { tools: true, elicitation: true },
+            tools: toolsForPublicDiscovery()
+          });
+        }
+
+        if (!isMcpPath(url.pathname)) {
+          return writeJson(req, res, 404, { error: 'not_found', requestId });
+        }
+
+        // Ensure transport responses expose session headers for browser/Electron clients.
+        setCorsHeaders(req, res);
+
+        if (!requireAuth(req, res)) return;
+        if (!requireProtocolHeader(req, res)) return;
+
+
+        if (req.method === 'POST') {
+          let raw = '';
+          req.setEncoding('utf8');
+          req.on('data', (chunk) => { raw += chunk; });
+          req.on('end', async () => {
+            let parsedBody;
+            try {
+              parsedBody = raw ? JSON.parse(raw) : undefined;
+              req._mcpParsedBody = parsedBody;
+            } catch {
+              return writeJson(req, res, 400, { error: 'invalid_json', requestId });
+            }
+
+            // Add timeout protection (5 minutes)
+            const timeoutMs = 5 * 60 * 1000;
+            const timeoutId = setTimeout(() => {
+              log('error', 'mcp_request_timeout', { requestId, timeoutMs, method: req.method, path: url.pathname });
+              if (!res.headersSent) {
+                writeJson(req, res, 504, {
+                  error: 'timeout',
+                  message: 'Request timeout after 5 minutes',
+                  requestId
+                });
+              }
+            }, timeoutMs);
+
+            try {
+              const { server: requestServer, transport: httpTransport } = await createStatelessTransport(req);
+              res.once('close', () => {
+                try {
+                  httpTransport.close();
+                } catch (e) {
+                  log('warn', 'mcp_transport_close_error', { requestId, message: e?.message });
+                }
+                try {
+                  if (typeof requestServer?.close === 'function') requestServer.close();
+                } catch (e) {
+                  log('warn', 'mcp_server_close_error', { requestId, message: e?.message });
+                }
+              });
+              await httpTransport.handleRequest(req, res, parsedBody);
+              clearTimeout(timeoutId);
+            } catch (transportError) {
+              clearTimeout(timeoutId);
+              log('error', 'mcp_transport_error', { requestId, message: transportError?.message || 'unknown_error' });
+              if (!res.headersSent) {
+                writeJson(req, res, 500, {
+                  error: 'transport_error',
+                  message: transportError.message,
+                  requestId
+                });
+              }
+            }
+          });
+          return;
+        }
+
+        if (req.method === 'GET' || req.method === 'DELETE') {
+          return writeJson(req, res, 405, {
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              message: 'Method not allowed.'
+            },
+            id: null,
+            requestId
+          });
+        }
+
+        return writeJson(req, res, 405, { error: 'method_not_allowed', requestId });
+      } catch (err) {
+        // Map error types to HTTP status codes
+        const statusCode = err?.statusCode || (err?.status >= 400 && err?.status < 600 ? err.status : 500);
+        const is4xx = statusCode >= 400 && statusCode < 500;
+        const is5xx = statusCode >= 500;
+        
+        log('error', 'mcp_request_error', {
+          requestId,
+          statusCode,
+          error: err?.message || 'unknown',
+          is4xx,
+          is5xx
+        });
+        
+        writeJson(req, res, statusCode, {
+          error: is4xx ? 'client_error' : 'server_error',
+          message: err?.message || 'unknown',
+          requestId,
+          statusCode
+        });
+      }
+    });
+
+    httpServer.listen(port, host, () => {
+      log('info', 'mcp_http_started', {
+        publicUrl: `${MCP_PUBLIC_URL}${mcpPath}`,
+        bind: `http://${host}:${port}${mcpPath}`,
+        api: NEUS_API_URL,
+        appId: MCP_APP_ID,
+        toolsTotal: TOOLS.length,
+        toolsPublicDiscovery: PUBLIC_MCP_TOOL_NAMES_ORDERED.length,
+        extendedToolsPolicy: mcp.mcpExtendedToolsPolicy
+      });
+      if (!enableDnsRebindingProtection) {
+        log('warn', 'mcp_dns_rebinding_protection_disabled', {
+          message: 'Set MCP_ALLOWED_ORIGINS and/or MCP_ALLOWED_HOSTS in production.'
+        });
+      }
+    });
+
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      log('info', 'mcp_shutdown_start', { signal });
+      const forceExitTimer = setTimeout(() => {
+        log('error', 'mcp_shutdown_forced', { signal, timeoutMs: SHUTDOWN_TIMEOUT_MS });
+        process.exit(1);
+      }, SHUTDOWN_TIMEOUT_MS);
+      forceExitTimer.unref?.();
+      httpServer.close((err) => {
+        if (err) {
+          log('error', 'mcp_shutdown_error', { signal, message: err.message });
+          process.exit(1);
+        }
+        clearTimeout(forceExitTimer);
+        log('info', 'mcp_shutdown_complete', { signal });
+        process.exit(0);
+      });
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+
+    return;
+  }
+
+  // MCP_TRANSPORT=stdio uses the same public allowlist by default as hosted MCP.
+  const stdioExposeExtended = await resolveMcpExtendedToolsExposure(null);
+  const stdioServer = createNeusServer(null, { exposeExtendedTools: stdioExposeExtended });
+  const stdioTransport = new StdioServerTransport();
+  await stdioServer.connect(stdioTransport);
+  log('info', 'mcp_stdio_started', {
+    api: NEUS_API_URL,
+    appId: MCP_APP_ID,
+    toolsRegistered: stdioExposeExtended ? TOOLS.length : PUBLIC_MCP_TOOL_NAMES_ORDERED.length,
+    exposeExtendedTools: stdioExposeExtended,
+    extendedToolsPolicy: mcp.mcpExtendedToolsPolicy
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch((err) => {
+    log('error', 'mcp_fatal', {
+      message: err?.message || 'unknown_error',
+      stack: err?.stack || null
+    });
+    process.exit(1);
+  });
+}
+
+export {
+  buildMcpAssistantInstructions,
+  createNeusServer,
+  resolveMcpExtendedToolsExposure,
+  toolNamesForExposure,
+  toolsForPublicDiscovery,
+  PUBLIC_MCP_TOOL_NAMES_ORDERED
+};