@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -1,8 +1,31 @@
 import { describe, expect, it, vi, afterEach } from 'vitest';
-import { descriptorsFromMcpJson } from '../mcp-json-discovery.js';
+import { descriptorsFromMcpJson, judgeMcpServerEntry } from '../mcp-json-discovery.js';
 
 afterEach(() => vi.restoreAllMocks());
 
+describe('judgeMcpServerEntry', () => {
+  it('keeps every accepted header and env key — one spelled __proto__ included', () => {
+    // Parsed from text, as a repository file is: JSON.parse makes `__proto__`
+    // an own key, and a plain-object copy would turn it into a prototype
+    // assignment and lose it.
+    const http = judgeMcpServerEntry(
+      'vendor',
+      JSON.parse('{"type":"streamable-http","url":"https://x.example","headers":{"__proto__":"p","X-A":"a"}}'),
+    );
+    expect(http.ok).toBe(true);
+    if (!http.ok || http.transport !== 'streamable-http') throw new Error('unreachable');
+    expect(Object.keys(http.entry.headers ?? {}).sort()).toEqual(['X-A', '__proto__']);
+    expect(http.entry.headers?.['__proto__']).toBe('p');
+
+    const stdio = judgeMcpServerEntry(
+      'launch',
+      JSON.parse('{"type":"stdio","command":"run","env":{"__proto__":"p"}}'),
+    );
+    if (!stdio.ok || stdio.transport !== 'stdio') throw new Error('unreachable');
+    expect(stdio.entry.env?.['__proto__']).toBe('p');
+  });
+});
+
 const MANIFEST = JSON.stringify({
   name: 'gtm',
   extensions: {
@@ -37,6 +60,17 @@ describe('descriptorsFromMcpJson', () => {
     ]);
   });
 
+  it('refuses an sse server rather than rebuilding it as a transport it is not', () => {
+    // The pinned MCP client has no sse transport; emitting `http` for an sse
+    // server configures a handshake the server does not speak.
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({ mcpServers: { legacy: { type: 'sse', url: 'https://mcp.legacy.example/sse' } } }),
+      null,
+    );
+    expect(out).toEqual([]);
+  });
+
   it('merges extension auth over mcp.json literals and carries variables + description', () => {
     const out = descriptorsFromMcpJson(
       'GTM',

package/src/modules/tool-manuals/__tests__/tool-manuals.cli.test.ts

@@ -192,6 +192,8 @@ describe('manual namespaces are unique, not merely manual names', () => {
    */
   async function writeMcpServer(folder: string, serverName: string): Promise<void> {
     await mkdir(join(pluginsDir(), folder), { recursive: true });
+    // A plugin is a folder with a manifest; the servers ride in its mcp.json.
+    await writeFile(join(pluginsDir(), folder, 'plugin.json'), `{"name":"${folder.toLowerCase()}"}`);
     await writeFile(
       join(pluginsDir(), folder, 'mcp.json'),
       JSON.stringify({ mcpServers: { [serverName]: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),

package/src/modules/tool-manuals/__tests__/tool-manuals.health-check.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeToolManual } from '../tool-manuals.service.js';
+
+/**
+ * The `healthCheck:` block is a URL this SERVER will fetch with the caller's
+ * credential attached, unattended, on every save and re-check. That makes it a
+ * second fetch target on the same footing as the manual's own `url`, so it is
+ * policed by the same SSRF rule — and held to one extra rule of its own: it may
+ * not mutate.
+ */
+
+const toolFile = (body: string) => `---
+name: acme
+type: http
+url: https://api.acme.test/utcp
+headers:
+  Authorization: Bearer \${API_KEY}
+${body}---
+notes
+`;
+
+const parse = (body: string) => normalizeToolManual('acme', 'Plugins/acme.tool', toolFile(body));
+
+describe('`.tool` healthCheck', () => {
+  it('is absent when nothing is declared — the tool is simply unverifiable', () => {
+    expect(parse('').healthCheck).toBeUndefined();
+  });
+
+  it('inherits the manual\'s headers, so a one-line declaration still authenticates', () => {
+    // This is what makes the common case cheap: the credential already lives in
+    // `headers`, and re-typing it on the probe would be a chance to get it wrong.
+    expect(parse('healthCheck:\n  url: https://api.acme.test/me\n').healthCheck).toEqual({
+      url: 'https://api.acme.test/me',
+      headers: { Authorization: 'Bearer ${API_KEY}' },
+    });
+  });
+
+  it('keeps its own headers when it declares them', () => {
+    const hc = parse('healthCheck:\n  url: https://api.acme.test/me\n  headers:\n    X-Key: ${API_KEY}\n').healthCheck;
+    expect(hc?.headers).toEqual({ 'X-Key': '${API_KEY}' });
+  });
+
+  it("an INLINE manual's probe inherits NO top-level headers — execution never sends them", () => {
+    // An inline manual's real calls go through each embedded tool's own call
+    // template; nothing ever sends the manual's top-level `headers:`. A probe
+    // that inherited them proved a request no call makes — `Connected` about
+    // the wrong request. An inline probe declares its headers on the
+    // healthCheck itself, or sends none.
+    const inline = normalizeToolManual(
+      'acme',
+      'Plugins/acme.tool',
+      `---
+name: acme
+type: inline
+headers:
+  Authorization: Bearer \${API_KEY}
+healthCheck:
+  url: https://api.acme.test/me
+tools: []
+---
+`,
+    );
+    expect(inline.healthCheck?.headers).toBeUndefined();
+  });
+
+  it('refuses a method that could mutate', () => {
+    // Silently downgrading POST to GET would leave the author believing they had
+    // declared something we are not doing.
+    expect(() => parse('healthCheck:\n  url: https://api.acme.test/me\n  method: POST\n')).toThrow(
+      /may not mutate/,
+    );
+  });
+
+  it('refuses a probe pointed at an internal host', () => {
+    expect(() => parse('healthCheck:\n  url: http://169.254.169.254/latest/meta-data\n')).toThrow(
+      /not allowed/,
+    );
+  });
+
+  it('refuses a declaration with no url', () => {
+    expect(() => parse('healthCheck:\n  method: GET\n')).toThrow(/must have a `url`/);
+  });
+
+  /**
+   * A local-only `.tool` is never fetched by this server, so its probe is exempt
+   * from the guard for exactly the same reason its `url` is.
+   */
+  it('exempts a local-only tool, as it does for the manual url', () => {
+    const local = normalizeToolManual(
+      'acme',
+      'Plugins/acme.tool',
+      `---
+name: acme
+type: http
+remote: false
+url: http://localhost:9000/utcp
+healthCheck:
+  url: http://localhost:9000/me
+---
+`,
+    );
+    expect(local.healthCheck?.url).toBe('http://localhost:9000/me');
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -82,6 +82,62 @@ describe('ToolManualService', () => {
     expect(list.find((m) => m.name === 'billing')!.type).toBe('http');
   });
 
+  test('surfaces a variable referenced ONLY by a health check, and keeps the probe off the summary', async () => {
+    // Two halves of the same contract. The probe's `${VAR}` has to reach the
+    // secrets UI or nobody can ever fill it in and the tool reports
+    // `unverifiable` forever — but the probe's HEADERS must not ride the
+    // browser-facing summary, since a `.tool` may write a literal token there.
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(
+      join(tools, 'probe.tool'),
+      JSON.stringify({
+        name: 'probe',
+        type: 'http',
+        url: 'https://api.example.com/utcp',
+        healthCheck: { url: 'https://api.example.com/me', headers: { 'X-Key': '${PROBE_ONLY_KEY}' } },
+      }),
+    );
+
+    const summary = (await svc().listAccessible('user@x.eu')).find((m) => m.name === 'probe')!;
+    expect(summary.variables?.map((v) => v.name)).toContain('PROBE_ONLY_KEY');
+    expect(summary).not.toHaveProperty('healthCheck');
+
+    // The server still reaches it, through the accessor that never serializes.
+    const target = await svc().probeTargetFor('user@x.eu', 'probe');
+    expect(target?.healthCheck?.headers).toEqual({ 'X-Key': '${PROBE_ONLY_KEY}' });
+  });
+
+  test('builds a call template only for the probe that actually dials one', async () => {
+    // The template is dialled by exactly one probe: an `mcp` manual, reachable
+    // from this process, that declared no health check. Building it for the
+    // others costs a validation pass per probe and warn-logs about a value
+    // nothing was going to use.
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(
+      join(tools, 'chat.tool'),
+      JSON.stringify({ name: 'chat', type: 'mcp', url: 'https://mcp.example.com' }),
+    );
+    await writeFile(
+      join(tools, 'checked.tool'),
+      JSON.stringify({
+        name: 'checked',
+        type: 'mcp',
+        url: 'https://mcp.example.com',
+        healthCheck: { url: 'https://api.example.com/me' },
+      }),
+    );
+
+    const service = svc();
+    // Asserted through the template's own type, not `not.toBeNull()`: the
+    // optional chain yields `undefined` when the lookup itself fails, and
+    // `undefined` is not null — so the weaker form passes on no target at all.
+    expect((await service.probeTargetFor('user@x.eu', 'chat'))?.callTemplate?.call_template_type).toBe('mcp');
+    // A declared health check wins for every type, so this one never dials it.
+    expect((await service.probeTargetFor('user@x.eu', 'checked'))?.callTemplate).toBeNull();
+    // An http manual is probed only by what it declares, never by a handshake.
+    expect((await service.probeTargetFor('user@x.eu', 'billing'))?.callTemplate).toBeNull();
+  });
+
   test('ACL filters out manuals the user cannot read', async () => {
     const list = await svc(denyBilling).listAccessible('user@x.eu');
     expect(list.map((m) => m.name)).toEqual(['weather']);

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -195,6 +195,121 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
  * materialization is a later phase — so a stdio server relying on them will
  * fail to spawn until then; bare-command servers (`npx …`) work today.
  */
+/**
+ * The ONE judgement of an `mcp.json` server entry — its name and its
+ * transport — shared by the manual scanner (which layers the platform's
+ * extension data and its reachability gate on top), the bundle dialect's
+ * registry (whose configs become entries) and the marketplace compiler
+ * (which ships only what a client could run). An entry that fails here fails
+ * everywhere, for one reason; an entry that passes is returned NORMALISED to
+ * the portable shape every consumer emits.
+ */
+export type McpEntryVerdict =
+  | { ok: true; transport: 'stdio'; entry: PortableStdioEntry }
+  | { ok: true; transport: 'streamable-http'; entry: PortableHttpEntry }
+  | { ok: false; reason: string };
+
+/** A stdio server as a client launches it — every field already the type the launcher needs. */
+export interface PortableStdioEntry {
+  type: 'stdio';
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+/** An http server as a client dials it — an endpoint, never a credential. */
+export interface PortableHttpEntry {
+  type: 'streamable-http';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/**
+ * A record whose every value is a string, or null — no coercion, no cast.
+ * Built without a prototype: the keys are HTTP header and environment
+ * variable names, and a plain object would silently swallow one spelled
+ * `__proto__` (a prototype assignment, not a property) — every accepted key
+ * must come out the other side.
+ */
+function stringMap(v: unknown): Record<string, string> | null {
+  if (!isRecord(v)) return null;
+  const out: Record<string, string> = Object.create(null) as Record<string, string>;
+  for (const [k, val] of Object.entries(v)) {
+    if (typeof val !== 'string') return null;
+    out[k] = val;
+  }
+  return out;
+}
+
+export function judgeMcpServerEntry(name: string, raw: unknown): McpEntryVerdict {
+  // The name rule (lowercase, alphanumeric first) also keeps every object
+  // prototype key — `__proto__`, `constructor` — out of the plain-object
+  // maps consumers build from these names.
+  if (!SERVER_NAME_RE.test(name)) {
+    return {
+      ok: false,
+      reason: 'the name is the secret namespace and route slug, so it must be lowercase alphanumeric with `_`/`-`',
+    };
+  }
+  if (!isRecord(raw) || typeof raw.type !== 'string') return { ok: false, reason: 'no transport type' };
+  if (raw.type === 'stdio') {
+    if (typeof raw.command !== 'string' || raw.command.length === 0) return { ok: false, reason: 'no command' };
+    const entry: PortableStdioEntry = { type: 'stdio', command: raw.command, args: [] };
+    if (raw.args !== undefined) {
+      // A launcher gets the strings it was given, never a stringified object.
+      if (!Array.isArray(raw.args) || !raw.args.every((a) => typeof a === 'string')) {
+        return { ok: false, reason: 'args must be a list of strings' };
+      }
+      entry.args = raw.args;
+    }
+    if (raw.env !== undefined) {
+      const env = stringMap(raw.env);
+      if (env === null) return { ok: false, reason: 'env must be a map of strings' };
+      entry.env = env;
+    }
+    if (raw.cwd !== undefined) {
+      if (typeof raw.cwd !== 'string') return { ok: false, reason: 'cwd must be a string' };
+      entry.cwd = raw.cwd;
+    }
+    return { ok: true, transport: 'stdio', entry };
+  }
+  if (raw.type === 'sse') {
+    // The pinned `@utcp/mcp` speaks `stdio` and streamable `http` — there
+    // is no sse transport in its schema, so a declaration claiming one either
+    // fails validation or, worse, dials a handshake the server does not
+    // speak. Refusing names the fix; silently rebuilding as http used to
+    // configure exactly that wrong handshake.
+    return {
+      ok: false,
+      reason: 'the MCP client has no `sse` transport — declare the server as `streamable-http` if it supports it',
+    };
+  }
+  if (raw.type === 'streamable-http') {
+    if (typeof raw.url !== 'string' || raw.url.length === 0) return { ok: false, reason: 'no url' };
+    let parsed: URL;
+    try {
+      parsed = new URL(raw.url);
+    } catch {
+      return { ok: false, reason: 'url must be http(s)' };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return { ok: false, reason: 'url must be http(s)' };
+    // A portable entry is an endpoint. A credential belongs in the vault and
+    // reaches a client through the platform, never verbatim in a config that
+    // is compiled into a marketplace and cloned onto every member's machine.
+    if (parsed.username || parsed.password) return { ok: false, reason: 'url must not carry credentials' };
+    const entry: PortableHttpEntry = { type: 'streamable-http', url: raw.url };
+    if (raw.headers !== undefined) {
+      const headers = stringMap(raw.headers);
+      if (headers === null) return { ok: false, reason: 'headers must be a map of strings' };
+      entry.headers = headers;
+    }
+    return { ok: true, transport: 'streamable-http', entry };
+  }
+  // Unknown transport: the spec says an unknown `type` invalidates the
+  // ENTRY, not the file — the caller skips it and keeps its siblings.
+  return { ok: false, reason: `unknown type "${raw.type}"` };
+}
+
 export function descriptorsFromMcpJson(
   pluginFolder: string,
   mcpJsonText: string,
@@ -227,18 +342,14 @@ export function descriptorsFromMcpJson(
   const mcpJsonPath = `${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
 
   const out: ToolManualDescriptor[] = [];
-  for (const [name, raw] of Object.entries(mcp.mcpServers)) {
-    if (!SERVER_NAME_RE.test(name)) {
-      console.warn(
-        `[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: the name is the secret ` +
-          'namespace and route slug, so it must be lowercase alphanumeric with `_`/`-`.',
-      );
-      continue;
-    }
-    if (!isRecord(raw) || typeof raw.type !== 'string') {
-      console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: no transport type.`);
+  for (const [name, rawEntry] of Object.entries(mcp.mcpServers)) {
+    const verdict = judgeMcpServerEntry(name, rawEntry);
+    if (!verdict.ok) {
+      console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: ${verdict.reason}.`);
       continue;
     }
+    // Narrowed by the verdict: an entry that passed is a record.
+    const raw = rawEntry as Record<string, unknown>;
     // The extension entry is knowledge-base content too — same zero-trust
     // parse as the rest: a non-object entry reads as "no extension data".
     const ext: HexisMcpServerExtension = isRecord(extensions[name])
@@ -274,79 +385,46 @@ export function descriptorsFromMcpJson(
       ...(variables.length > 0 ? { variables } : {}),
     };
 
-    if (raw.type === 'stdio') {
-      if (typeof raw.command !== 'string' || raw.command.length === 0) {
-        console.warn(`[tool-manuals] skipping stdio server "${name}" in ${mcpJsonPath}: no command.`);
-        continue;
-      }
-      out.push({
-        ...shared,
-        remote: false,
-        stdio: {
-          command: raw.command,
-          args: Array.isArray(raw.args) ? raw.args.map(String) : [],
-          env: isRecord(raw.env) ? (raw.env as Record<string, string>) : undefined,
-          cwd: typeof raw.cwd === 'string' ? raw.cwd : undefined,
-        },
-      });
+    if (verdict.transport === 'stdio') {
+      const { command, args, env, cwd } = verdict.entry;
+      out.push({ ...shared, remote: false, stdio: { command, args, env, cwd } });
       continue;
     }
 
-    if (raw.type === 'streamable-http' || raw.type === 'sse') {
-      if (typeof raw.url !== 'string' || raw.url.length === 0) {
-        console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: no url.`);
-        continue;
-      }
-      // Remote-capable servers get the same SSRF gate `.tool` urls pass —
-      // otherwise mcp.json becomes the way to point the backend at loopback,
-      // private ranges, or the cloud metadata endpoint. A `local: true` entry
-      // is exempt because loopback is exactly what local MEANS, and only the
-      // user's own machine ever dials it.
-      // Scheme first, for EVERYONE: `local: true` exempts a server from the
-      // private-network reachability policy, not from being http(s) at all.
-      let schemeOk = false;
+    const url = verdict.entry.url;
+    // Remote-capable servers get the same SSRF gate `.tool` urls pass —
+    // otherwise mcp.json becomes the way to point the backend at loopback,
+    // private ranges, or the cloud metadata endpoint. A `local: true` entry
+    // is exempt because loopback is exactly what local MEANS, and only the
+    // user's own machine ever dials it. (The scheme itself was judged for
+    // everyone above: `local: true` exempts a server from the reachability
+    // policy, not from being http(s) at all.)
+    if (ext.local !== true) {
       try {
-        const u = new URL(raw.url);
-        schemeOk = u.protocol === 'http:' || u.protocol === 'https:';
-      } catch {
-        schemeOk = false;
-      }
-      if (!schemeOk) {
-        console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: url must be http(s).`);
+        assertSafeFetchUrl(url, { label: `mcp server "${name}" url` });
+      } catch (err) {
+        console.warn(
+          `[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: ` +
+            `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
+        );
         continue;
       }
-      if (ext.local !== true) {
-        try {
-          assertSafeFetchUrl(raw.url, { label: `mcp server "${name}" url` });
-        } catch (err) {
-          console.warn(
-            `[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: ` +
-              `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
-          );
-          continue;
-        }
-      }
-      // Extension headers (auth, `${VAR}` refs) win over mcp.json's literal
-      // ones on a key collision: the portable file cannot carry a credential,
-      // so when both name the same header the extension is the operative one.
-      // Both sides pass the isRecord gate — spreading a malformed non-object
-      // value (a string, say) would scatter its indices into header keys.
-      const headers = {
-        ...(isRecord(raw.headers) ? (raw.headers as Record<string, string>) : {}),
-        ...(isRecord(ext.headers) ? (ext.headers as Record<string, string>) : {}),
-      };
-      out.push({
-        ...shared,
-        url: raw.url,
-        ...(Object.keys(headers).length > 0 ? { headers } : {}),
-        ...(ext.local === true ? { remote: false } : {}),
-      });
-      continue;
     }
-
-    // Unknown transport: the spec says an unknown `type` invalidates the
-    // ENTRY, not the file — skip it, keep its siblings.
-    console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: unknown type "${raw.type}".`);
+    // Extension headers (auth, `${VAR}` refs) win over mcp.json's literal
+    // ones on a key collision: the portable file cannot carry a credential,
+    // so when both name the same header the extension is the operative one.
+    // Both sides pass the isRecord gate — spreading a malformed non-object
+    // value (a string, say) would scatter its indices into header keys.
+    const headers = {
+      ...(verdict.entry.headers ?? {}),
+      ...(isRecord(ext.headers) ? (ext.headers as Record<string, string>) : {}),
+    };
+    out.push({
+      ...shared,
+      url,
+      ...(Object.keys(headers).length > 0 ? { headers } : {}),
+      ...(ext.local === true ? { remote: false } : {}),
+    });
   }
   return out;
 }

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -174,10 +174,19 @@ export class McpServerEditService {
     const servers = mcp.mcpServers as Record<string, unknown>;
     if (!(name in servers)) throw new McpServerEditError('No such server.', 404);
 
-    if (write.transport !== 'streamable-http' && write.transport !== 'sse' && write.transport !== 'stdio') {
-      // Persisting an unknown transport would save an entry discovery then
-      // refuses — an unusable server with no error at the moment it was made.
-      throw new McpServerEditError(`Unknown transport "${String(write.transport)}".`, 422);
+    if (write.transport !== 'streamable-http' && write.transport !== 'stdio') {
+      // Persisting a transport discovery refuses would save an entry that
+      // vanishes from the catalog the moment it is written — an unusable
+      // server with no error at the moment it was made. `sse` is refused BY
+      // NAME with the fix spelled out, because the pinned MCP client has no
+      // sse transport; an EXISTING sse entry stays readable here, so it can
+      // be edited to `streamable-http` rather than being stranded.
+      throw new McpServerEditError(
+        write.transport === 'sse'
+          ? 'The MCP client has no `sse` transport — declare the server as `streamable-http` if it supports it.'
+          : `Unknown transport "${String(write.transport)}".`,
+        422,
+      );
     }
     // The EFFECTIVE value of every field, PATCH-over-stored (see
     // McpServerWrite): `undefined` keeps what the files already say, a

package/src/modules/tool-manuals/tool-manuals.contract.ts

@@ -88,6 +88,57 @@ export interface ToolVariable {
   oauth?: ToolVariableOAuth;
 }
 
+/**
+ * An optional cheap, read-only call that proves a credential actually WORKS.
+ *
+ * A `type: mcp` manual needs none — its handshake is authenticated, so merely
+ * connecting already tests the token. `http` and `inline` manuals have no such
+ * moment: registering an `http` manual fetches its DESCRIPTION, which providers
+ * usually serve publicly, so a wrong key sails through; an `inline` manual's
+ * discovery template points at Bevel's own API and never touches the provider
+ * at all. Without a declaration there is genuinely nothing to call, and the
+ * platform reports the connection as unverified rather than guessing.
+ *
+ * NOT inferred from the manual's own tools. Picking one automatically would
+ * mean calling an arbitrary tool with invented arguments — a probe that could
+ * send a message or create a record is worse than no probe. The author names a
+ * safe endpoint or the tool stays unverified.
+ *
+ * `${VAR}` refs resolve from the caller's vault exactly as they do in `url` and
+ * `headers`, which is the whole point: the probe must carry the same credential
+ * the real calls carry. Any 2xx is a pass; 401/403 is a rejection; anything
+ * else is treated as the provider being unwell rather than the key being wrong.
+ */
+export interface ToolHealthCheck {
+  /** Absolute URL to call. May contain `${VAR}` refs; SSRF-checked like `url`. */
+  url: string;
+  /** Default `GET`. A health check may not mutate, so nothing else is allowed. */
+  method?: 'GET';
+  /** Defaults to the manual's own `headers` — usually where the credential is. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * One manual, reduced to exactly what testing its credential requires.
+ *
+ * Server-internal, like {@link ToolHealthCheck} and for the same reason: both
+ * `healthCheck.headers` and `callTemplate` can carry a literal token.
+ */
+export interface ToolProbeTarget {
+  name: string;
+  type: ToolManualType;
+  /** `false` for a local-only tool this server is not the one that can reach it. */
+  remote?: boolean;
+  /** The probe the `.tool` declares, if any. */
+  healthCheck?: ToolHealthCheck;
+  /**
+   * The validated UTCP call template, or `null` when the manual doesn't produce
+   * a valid one. Only the `mcp` probe uses it — its handshake IS the test — but
+   * it is built here so the probe never has to walk the catalog again.
+   */
+  callTemplate: CallTemplate | null;
+}
+
 /**
  * For a `type: mcp` tool, what an admin must do to make the remote server
  * reachable — derived from OAuth auto-discovery, which a non-mcp tool has no
@@ -140,6 +191,15 @@ export interface ToolManualDescriptorBase {
   variables?: ToolVariable[];
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  /**
+   * Optional credential probe — see {@link ToolHealthCheck}. Declared on
+   * `http`/`inline` manuals, and honoured on `type: mcp` too, where it
+   * OVERRIDES the default handshake probe (a server whose health endpoint is
+   * cheaper or more truthful than a full MCP handshake says so here).
+   * INTERNAL: lives on the descriptor, never on {@link ToolManualSummary},
+   * because it carries `headers`.
+   */
+  healthCheck?: ToolHealthCheck;
 }
 
 /** The spawn spec of a stdio-declared MCP server (a plugin `mcp.json` entry). */
@@ -197,6 +257,10 @@ export interface ToolManualSummary {
   remote?: boolean;
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  // NOTE: no `healthCheck` here, deliberately. This type is serialized straight
+  // to the browser by the tool endpoints, and a probe carries `headers` — which
+  // a `.tool` author may write as a literal token rather than a `${VAR}` ref.
+  // The server reads probe config through `IToolManualService.probeTargetFor`.
 }
 
 /** One thing an `inline` manual's embedded tool list says the assistant can do. */
@@ -269,6 +333,31 @@ export interface IToolManualService {
    * a `resolve` reads the shared row or the caller's row.
    */
   scopeOfVariable(effectiveKey: string): Promise<ToolVariableScope>;
+  /**
+   * Everything the credential probe needs about one readable manual, resolved
+   * in a SINGLE catalog + ACL pass.
+   *
+   * One accessor rather than three because the probe needs three facts that all
+   * come from the same file — is it local-only, does it declare a health check,
+   * and what call template would reach it — and asking for them separately made
+   * one probe walk the catalog four times, building call templates for every
+   * manual in the workspace to use exactly one of them.
+   *
+   * Deliberately NOT reachable through {@link ToolManualSummary}: that type is
+   * serialized straight to the browser by the tool endpoints, and a probe
+   * carries `headers` — which a `.tool` author may write as a literal token
+   * rather than a `${VAR}` ref. Probe config is internal to the server, so it
+   * travels by its own accessor and never rides a public DTO.
+   *
+   * Addressed by SLUG, which is what the route has: resolving the slug here
+   * rather than making the caller map it to a name first is what reduces a
+   * probe to one pass. `ToolProbeTarget.name` carries the UTCP namespace back
+   * out, since that is what the probe's `${VAR}` lookups are keyed by.
+   *
+   * `null` when no such manual exists OR the caller can't read it — the two are
+   * indistinguishable on purpose, as everywhere else in this contract.
+   */
+  probeTargetFor(userEmail: string, slug: string): Promise<ToolProbeTarget | null>;
   /**
    * The per-user (`user`-scoped) variables a manual declares, each with the vault
    * key (`<manual>_<VAR>`) the caller's value is stored under, its bare name, and