melchizedek-agents 1.2.0 → 1.3.1

package/dist/lib/syndicateSchema.js

@@ -26,6 +26,7 @@ import { DEFAULT_ROUTE_KEY, NODE_KINDS, ROUTE_STEP_SUFFIX, START_NAME, elementNa
 import { isSecretShapedEnvName } from './tools/skills/env.js';
 import { OAUTH_SCOPE, PROVIDER_NAME } from './tools/auth.js';
 import { V2_AGENT_KEYS, conflictMessage, conflictsOf, toEngineAgent } from './agentDialect.js';
+import { MCP_TRANSPORTS } from './tools/mcpTransports.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's agent-name rule (validateAgentName in ADK's base_agent), kept: checked here
@@ -217,8 +218,12 @@ const oauth2Auth = z
     grant: z
         .enum(['authorization_code', 'client_credentials'])
         .describe('authorization_code: each user\'s own token, granted through the consent pause (ADR 0085). client_credentials: the server\'s own token, from the token endpoint.'),
-    authorization_url: z.string().url().optional().describe('The provider\'s authorization endpoint (https). authorization_code only.'),
-    token_url: z.string().url().describe('The provider\'s token endpoint (https).'),
+    client_registration: z
+        .literal('dynamic')
+        .optional()
+        .describe('"dynamic": an MCP server\'s authorization_code grant with no pre-issued client. The authorization server is discovered from the MCP server (RFC 9728, RFC 8414) and this deployment registers itself as a public PKCE client (RFC 7591), once per server and redirect URI, sealed in the credential store (ADR 0124). Every discovered host must be on the operator\'s OAuth host allowlist. MCP servers only; no client id, client secret or endpoint URL beside it.'),
+    authorization_url: z.string().url().optional().describe('The provider\'s authorization endpoint (https). authorization_code only; discovered with client_registration: dynamic.'),
+    token_url: z.string().url().optional().describe('The provider\'s token endpoint (https). Required, except with client_registration: dynamic, which discovers it.'),
     client_id: z.string().min(1).max(512).optional().describe('The OAuth client id, written out (it is not a secret). Or client_id_env.'),
     client_id_env: envName.optional().describe('Environment variable holding the client id. Or client_id.'),
     client_secret_env: envName
@@ -228,13 +233,25 @@ const oauth2Auth = z
     authorization_params: z
         .record(z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/), z.string().max(512))
         .optional()
-        .describe('Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.'),
+        .describe('Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id, resource or the PKCE pair.'),
 })
     .superRefine((o, ctx) => {
-    if (!!o.client_id === !!o.client_id_env)
-        ctx.addIssue({ code: 'custom', path: ['client_id'], message: 'exactly one of client_id or client_id_env' });
-    if (o.grant === 'authorization_code' && !o.authorization_url) {
-        ctx.addIssue({ code: 'custom', path: ['authorization_url'], message: 'an authorization_code grant needs authorization_url' });
+    if (o.client_registration === 'dynamic') {
+        if (o.grant !== 'authorization_code')
+            ctx.addIssue({ code: 'custom', path: ['client_registration'], message: 'client_registration: dynamic is for an authorization_code grant' });
+        for (const key of ['client_id', 'client_id_env', 'client_secret_env', 'authorization_url', 'token_url']) {
+            if (o[key] !== undefined)
+                ctx.addIssue({ code: 'custom', path: [key], message: `${key} cannot be combined with client_registration: dynamic, which discovers the endpoints and registers the client (ADR 0124)` });
+        }
+    }
+    else {
+        if (!!o.client_id === !!o.client_id_env)
+            ctx.addIssue({ code: 'custom', path: ['client_id'], message: 'exactly one of client_id or client_id_env' });
+        if (o.token_url === undefined)
+            ctx.addIssue({ code: 'custom', path: ['token_url'], message: 'token_url is required (on an MCP server, client_registration: dynamic discovers it)' });
+        if (o.grant === 'authorization_code' && !o.authorization_url) {
+            ctx.addIssue({ code: 'custom', path: ['authorization_url'], message: 'an authorization_code grant needs authorization_url' });
+        }
     }
     if (o.grant === 'client_credentials') {
         if (!o.client_secret_env)
@@ -244,13 +261,37 @@ const oauth2Auth = z
                 ctx.addIssue({ code: 'custom', path: [key], message: `${key} is for authorization_code only` });
         }
     }
-    const reserved = ['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope'];
+    const reserved = ['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope', 'resource'];
     for (const key of Object.keys(o.authorization_params ?? {})) {
         if (reserved.includes(key))
             ctx.addIssue({ code: 'custom', path: ['authorization_params', key], message: `authorization_params may not set "${key}"` });
     }
 })
     .describe('An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values.');
+// ── MCP (ADR 0124) ───────────────────────────────────────────────────────────
+const mcpTransport = z
+    .enum(MCP_TRANSPORTS)
+    .describe('How the MCP server is reached: auto (the default) tries Streamable HTTP and falls back to the legacy SSE transport on the spec\'s signal; streamable_http or sse use that one only (ADR 0124).');
+/** An `mcp_servers` entry's name: lowercase, bounded, one character class (no backtracking). */
+export const MCP_SERVER_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const mcpServerEntry = z
+    .strictObject({
+    name: z
+        .string()
+        .regex(MCP_SERVER_NAME, 'lowercase letters, digits, _ and -, starting with a letter (at most 64)')
+        .describe('A short name for the server, unique on this agent: logs and errors name it.'),
+    url: z.string().url().describe('The MCP server\'s URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard.'),
+    tools: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('The server\'s tools this agent may use, by name; any other tool it lists is not exposed. A name may appear on one server only, and never among the agent\'s own tools. require_approval may name these.'),
+    auth: z
+        .strictObject({ oauth2: oauth2Auth })
+        .optional()
+        .describe('The OAuth grant this server takes (ADR 0112, ADR 0124). Without it, MCP_BEARER_TOKENS applies.'),
+    transport: mcpTransport.optional(),
+})
+    .describe('One MCP server among several (ADR 0124).');
 // ── OpenAPI ──────────────────────────────────────────────────────────────────
 const openapiEntry = z
     .strictObject({
@@ -326,7 +367,7 @@ const agentFields = {
     mcp_server_url: z
         .string()
         .optional()
-        .describe('MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.'),
+        .describe('MCP server (Streamable HTTP, or legacy SSE) whose tools are discovered at runtime and merged with `tools`. For more than one server, use mcp_servers.'),
     mcp_tools: z
         .array(z.string().min(1))
         .min(1)
@@ -336,6 +377,13 @@ const agentFields = {
         .strictObject({ oauth2: oauth2Auth })
         .optional()
         .describe('The OAuth grant the MCP server takes (ADR 0112). With authorization_code, each user\'s own token on their own connection, and mcp_tools is required. Needs mcp_server_url; replaces MCP_BEARER_TOKENS for this server.'),
+    mcp_transport: mcpTransport.optional().describe('How mcp_server_url is reached: auto (the default), streamable_http or sse (ADR 0124). Needs mcp_server_url.'),
+    mcp_servers: z
+        .array(mcpServerEntry)
+        .min(1)
+        .max(16)
+        .optional()
+        .describe('Several MCP servers, each with the tools this agent may use from it, its grant and its transport (ADR 0124). Cannot be combined with mcp_server_url.'),
     skills: skillsSchema.optional(),
     openapi: z.array(openapiEntry).min(1).optional(),
     code_execution: z
@@ -678,6 +726,61 @@ export const REASONING_OLDER_SPELLING = ['thinkingConfig', 'reasoningEffort'];
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 /** Same normalisation lib/dispatch.ts uses to match a route to a subagent. */
 const routeNorm = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
+/** Every tool name an agent's `mcp_servers` entries list. */
+function mcpServerTools(agent) {
+    return (Array.isArray(agent.mcp_servers) ? agent.mcp_servers : []).flatMap((e) => (isObj(e) && Array.isArray(e.tools) ? e.tools.filter((t) => typeof t === 'string') : []));
+}
+/**
+ * An agent's `mcp_servers` against itself and its other keys (ADR 0124):
+ * not beside `mcp_server_url`; names unique; a tool name on one server only
+ * and never among the agent's own `tools` or OpenAPI `operations`, so no
+ * server can shadow another's tool or the agent's own; and dynamic client
+ * registration only here or under `mcp_auth`, never on an OpenAPI entry.
+ */
+function mcpServersProblems(agent, path) {
+    const out = [];
+    (Array.isArray(agent.openapi) ? agent.openapi : []).forEach((e, i) => {
+        if (isObj(e) && isObj(e.auth) && isObj(e.auth.oauth2) && e.auth.oauth2.client_registration !== undefined) {
+            out.push({ path: [...path, 'openapi', i, 'auth', 'oauth2', 'client_registration'], message: 'client_registration: dynamic discovers its endpoints from an MCP server; an OpenAPI entry names its own (ADR 0124)' });
+        }
+    });
+    if (!Array.isArray(agent.mcp_servers))
+        return out;
+    if (agent.mcp_server_url !== undefined) {
+        out.push({ path: [...path, 'mcp_servers'], message: 'cannot be combined with mcp_server_url: list that server as one more mcp_servers entry (ADR 0124)' });
+    }
+    const own = new Set([
+        ...(Array.isArray(agent.tools) ? agent.tools.filter((t) => typeof t === 'string') : []),
+        ...(Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations.filter((t) => typeof t === 'string') : [])),
+    ]);
+    const names = new Map();
+    const owner = new Map();
+    agent.mcp_servers.forEach((entry, i) => {
+        if (!isObj(entry))
+            return;
+        const name = typeof entry.name === 'string' ? entry.name : `#${i}`;
+        if (typeof entry.name === 'string') {
+            if (names.has(entry.name))
+                out.push({ path: [...path, 'mcp_servers', i, 'name'], message: `'${entry.name}' names mcp_servers entry ${names.get(entry.name)} too; each server's name is unique on the agent` });
+            else
+                names.set(entry.name, i);
+        }
+        (Array.isArray(entry.tools) ? entry.tools : []).forEach((tool, j) => {
+            if (typeof tool !== 'string')
+                return;
+            if (own.has(tool)) {
+                out.push({ path: [...path, 'mcp_servers', i, 'tools', j], message: `'${tool}' is also one of this agent's own tools; an MCP server's tool may not share a name with it (ADR 0124)` });
+            }
+            else if (owner.has(tool) && owner.get(tool) !== name) {
+                out.push({ path: [...path, 'mcp_servers', i, 'tools', j], message: `'${tool}' is also listed on MCP server '${owner.get(tool)}'; a tool name may come from one server only (ADR 0124)` });
+            }
+            else {
+                owner.set(tool, name);
+            }
+        });
+    });
+    return out;
+}
 /**
  * Rules that span fields, which a JSON Schema an editor reads cannot express
  * cleanly. Defensive about shape: runs on raw input alongside zod, so a file
@@ -713,10 +816,10 @@ function crossFieldProblems(raw) {
         // An OpenAPI operation can be gated once it is named under `operations`,
         // and an MCP tool once it is named under `mcp_tools`.
         const operations = (Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations : []));
-        const mcpTools = Array.isArray(agent.mcp_tools) ? agent.mcp_tools : [];
+        const mcpTools = [...(Array.isArray(agent.mcp_tools) ? agent.mcp_tools : []), ...mcpServerTools(agent)];
         (Array.isArray(agent.require_approval) ? agent.require_approval : []).forEach((name, j) => {
             if (typeof name === 'string' && !tools.includes(name) && !operations.includes(name) && !mcpTools.includes(name)) {
-                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools, its openapi operations or its mcp_tools` });
+                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools, its openapi operations or its mcp_tools (or an mcp_servers entry's tools)` });
             }
         });
     };
@@ -772,6 +875,10 @@ function crossFieldProblems(raw) {
         if (isObj(agent.mcp_auth) && isObj(agent.mcp_auth.oauth2) && agent.mcp_auth.oauth2.grant === 'authorization_code' && agent.mcp_tools === undefined) {
             out.push({ path: [...path, 'mcp_auth'], message: 'an authorization_code mcp_auth needs mcp_tools: no user\'s grant exists at startup to list the server\'s tools' });
         }
+        if (agent.mcp_transport !== undefined && typeof agent.mcp_server_url !== 'string') {
+            out.push({ path: [...path, 'mcp_transport'], message: 'mcp_transport is how mcp_server_url is reached; it needs mcp_server_url (an mcp_servers entry names its own transport)' });
+        }
+        out.push(...mcpServersProblems(agent, path));
     };
     if (isObj(raw.orchestrator))
         executionProblems(raw.orchestrator, ['orchestrator'], true);

package/dist/lib/tools/credentialUses.d.ts

@@ -36,7 +36,7 @@ export interface CredentialUse {
 }
 /** The parts of an `oauth2` block read here. */
 interface OAuth2Like {
-    token_url: string;
+    token_url?: string;
     client_secret_env?: string;
 }
 /** The parts of an `openapi:` entry read here. */
@@ -58,6 +58,12 @@ interface AgentLike {
     mcp_auth?: {
         oauth2?: OAuth2Like;
     };
+    mcp_servers?: Array<{
+        url?: string;
+        auth?: {
+            oauth2?: OAuth2Like;
+        };
+    }>;
     yaml_reference?: string;
 }
 /** The parts of a syndicate config read here. */

package/dist/lib/tools/credentialUses.js

@@ -16,6 +16,8 @@
 import { resolve } from 'node:path';
 import { credentialHostProblem, credentialHosts } from './credentialHosts.js';
 import { openApiServers } from './openapiTools.js';
+/** The token endpoint a client secret goes to; none named yet for a grant whose endpoints are discovered (ADR 0124). */
+const tokenUrlOf = (o) => (o.token_url ? [o.token_url] : []);
 /** The credential variables one agent's tools send. */
 export function agentCredentialUses(agent, prefix = '') {
     const name = `${prefix}${agent.name ?? ''}`;
@@ -31,11 +33,17 @@ export function agentCredentialUses(agent, prefix = '') {
         if (auth.api_key?.env)
             out.push({ agent: name, tools, env: auth.api_key.env, role: 'api_key', ...servers, openapi: entry });
         if (auth.oauth2?.client_secret_env)
-            out.push({ agent: name, tools, env: auth.oauth2.client_secret_env, role: 'client_secret_env', destinations: [auth.oauth2.token_url] });
+            out.push({ agent: name, tools, env: auth.oauth2.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(auth.oauth2) });
     }
     const mcp = agent.mcp_auth?.oauth2;
     if (mcp?.client_secret_env)
-        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, env: mcp.client_secret_env, role: 'client_secret_env', destinations: [mcp.token_url] });
+        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, env: mcp.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(mcp) });
+    // Each mcp_servers entry's grant (ADR 0124), as the single server's.
+    for (const server of agent.mcp_servers ?? []) {
+        const o = server?.auth?.oauth2;
+        if (o?.client_secret_env)
+            out.push({ agent: name, tools: `mcp ${server.url ?? ''}`, env: o.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(o) });
+    }
     return out;
 }
 /**

package/dist/lib/tools/generateImageTool.js

@@ -38,7 +38,8 @@ export const generateImageContract = defineTool({
             console.error(`[ImageTool ERROR] Initialization failed: ${err.message}`);
             throw err;
         }
-        console.log(`[ImageTool] Parameters - Prompt: "${prompt}", Style: "${style ?? 'none'}", Aspect Ratio: "${aspect_ratio ?? 'none'}", Color Palette: "${color_palette ?? 'none'}"`);
+        // Sizes and which options are set, never their values: the prompt carries the person's words.
+        console.log(`[ImageTool] Parameters - prompt ${prompt.length} chars; set: ${[style && 'style', aspect_ratio && 'aspect_ratio', color_palette && 'color_palette'].filter(Boolean).join(', ') || 'none'}`);
         const ai = new GoogleGenAI({ apiKey });
         // Build a rich prompt that bakes in the structured parameters.
         const parts = [prompt];

package/dist/lib/tools/inspectImageTool.js

@@ -46,7 +46,7 @@ export const inspectImageContract = defineTool({
         image_path: z.string().describe('Path to the saved image, e.g. "outputs/image_1234.png".'),
     }),
     execute: async ({ image_path }) => {
-        console.log(`[InspectTool] Blind inventory requested for: ${image_path}`);
+        console.log(`[InspectTool] Blind inventory requested (path ${image_path.length} chars).`);
         // Confine reads to the outputs/ directory — this tool inventories
         // generated artifacts, not the filesystem. OUTPUTS_DIR env overrides
         // the cwd default (must match generateImageTool's).

package/dist/lib/tools/mcpToolFactory.d.ts

@@ -1,6 +1,8 @@
 import type { ToolDeclaration } from '../models/contract.ts';
 import type { RedirectPolicy } from '../net/redirects.ts';
 import type { OAuth2AuthConfig } from './oauthTools.ts';
+import { MCP_TRANSPORTS } from './mcpTransports.ts';
+import type { McpTransportKind } from './mcpTransports.ts';
 import type { Tool } from './tool.ts';
 export declare function assertSafeMcpUrl(raw: string, env?: NodeJS.ProcessEnv): Promise<URL>;
 export declare function mcpAuthHeaders(url: URL, env?: NodeJS.ProcessEnv): Record<string, string>;
@@ -23,6 +25,15 @@ export declare const mcpFetch: (input: string | URL | Request, init?: RequestIni
 export declare const MAX_MCP_DESCRIPTION_CHARS = 1000;
 /** Every tool's shared result limit (lib/tools/tool.ts). */
 export declare const MAX_MCP_RESULT_CHARS = 20000;
+export { MCP_TRANSPORTS };
+export type { McpTransportKind };
+/**
+ * True when a failed Streamable HTTP connect is the spec's signal that the
+ * server speaks only the older HTTP+SSE transport: the initialize POST
+ * answered with a 4xx (404, 405, 400 …). A 401 or 403 is the server refusing
+ * the credential, which another transport would not change.
+ */
+export declare function isSseFallbackSignal(error: unknown): boolean;
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
  * the process (its tools are called for the life of the compiled agent), and
@@ -44,10 +55,27 @@ export declare function mcpToolParameters(inputSchema: {
 } | undefined): ToolDeclaration['parameters'];
 /** How an agent reaches its MCP server: which tools it may use, and the OAuth grant the server takes. */
 export interface McpToolOptions {
-    /** `mcp_tools`: the names this agent may use. Required with an authorization_code grant. */
+    /** `mcp_tools` (or an `mcp_servers` entry's `tools`): the names this agent may use. Required with an authorization_code grant. */
     tools?: string[];
     /** `mcp_auth.oauth2` (ADR 0112). Without it, MCP_BEARER_TOKENS applies. */
     oauth2?: OAuth2AuthConfig;
+    /** `mcp_transport` (or an entry's `transport`): default `auto` (ADR 0124). */
+    transport?: McpTransportKind;
+}
+/**
+ * One entry of an agent's `mcp_servers:` list (ADR 0124): a server, the
+ * tools of it the agent may use, the grant it takes and its transport.
+ */
+export interface McpServerConfig {
+    /** A short name for the server, unique on the agent: logs and errors name it. */
+    name: string;
+    url: string;
+    /** The server's tools this agent may use, by name. Required: names across servers are refused on collision at load. */
+    tools: string[];
+    auth?: {
+        oauth2: OAuth2AuthConfig;
+    };
+    transport?: McpTransportKind;
 }
 /** Per-user connections at most per authorization-code server; the least recently used is closed first. */
 export declare const MAX_MCP_USER_CONNECTIONS = 64;

package/dist/lib/tools/mcpToolFactory.js

@@ -2,8 +2,11 @@
  * lib/tools/mcpToolFactory.ts — a remote MCP server's tools, as the
  * engine's own Tools (lib/tools/tool.ts, ADR 0062).
  *
- * An agent's `mcp_server_url:` connects here over SSE; every tool the
- * server lists becomes an own Tool whose declaration is the server's
+ * An agent's `mcp_server_url:` (or each entry of `mcp_servers:`, ADR 0124)
+ * connects here over Streamable HTTP, falling back to the legacy SSE
+ * transport when the server answers the initialize POST with the spec's
+ * fallback signal (a 4xx other than 401/403), or over the transport the YAML
+ * names. Every tool the server lists becomes an own Tool whose declaration is the server's
  * description (bounded) and input schema, and whose execute calls the
  * server and returns its text (bounded). loadMcpTools returns them;
  * createMcpTools is the name the compiler calls.
@@ -20,11 +23,13 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { toContractJsonSchema } from '../models/schemaNormalize.js';
 import { checkHost } from '../net/addressGuard.js';
 import { fetchWithRedirectPolicy } from '../net/redirects.js';
 import { ToolCredentialError } from './auth.js';
 import { oauthCallProblem, oauthTokenSource } from './oauthTools.js';
+import { MCP_TRANSPORTS } from './mcpTransports.js';
 import { MAX_RESULT_CHARS } from './tool.js';
 import { toGeminiSchema } from './toolContract.js';
 // Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
@@ -116,6 +121,54 @@ export const MAX_MCP_RESULT_CHARS = MAX_RESULT_CHARS;
 const bounded = (text, max, what) => text.length <= max ? text : `${text.slice(0, max)}… [${what} cut at ${max} characters]`;
 /** Every MCP connection opened and still in use, so a shutdown can close them. */
 const openTransports = new Set();
+export { MCP_TRANSPORTS };
+/**
+ * True when a failed Streamable HTTP connect is the spec's signal that the
+ * server speaks only the older HTTP+SSE transport: the initialize POST
+ * answered with a 4xx (404, 405, 400 …). A 401 or 403 is the server refusing
+ * the credential, which another transport would not change.
+ */
+export function isSseFallbackSignal(error) {
+    if (!(error instanceof StreamableHTTPError))
+        return false;
+    const code = error.code;
+    return typeof code === 'number' && code >= 400 && code < 500 && code !== 401 && code !== 403;
+}
+/**
+ * A client connected to `url` over `kind`, every request through `fetchFn`
+ * (the redirect rule, and the credential when there is one). A transport
+ * that fails to connect is closed before the error leaves, so nothing keeps
+ * reconnecting; with `auto`, a failed Streamable HTTP attempt carrying the
+ * fallback signal is closed and the SSE transport tried once.
+ */
+async function connectMcp(url, kind, fetchFn, headers = {}) {
+    const attempt = async (which) => {
+        const requestInit = Object.keys(headers).length ? { requestInit: { headers } } : {};
+        const transport = which === 'sse' ? new SSEClientTransport(url, { ...requestInit, fetch: fetchFn }) : new StreamableHTTPClientTransport(url, { ...requestInit, fetch: fetchFn });
+        const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            await transport.close().catch(() => { });
+            throw error;
+        }
+        openTransports.add(transport);
+        return { client, transport, kind: which };
+    };
+    if (kind === 'sse')
+        return attempt('sse');
+    if (kind === 'streamable_http')
+        return attempt('streamable_http');
+    try {
+        return await attempt('streamable_http');
+    }
+    catch (error) {
+        if (!isSseFallbackSignal(error))
+            throw error;
+        return attempt('sse');
+    }
+}
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
  * the process (its tools are called for the life of the compiled agent), and
@@ -204,23 +257,17 @@ const userPools = new Set();
  */
 export async function loadMcpTools(mcpServerUrl, options = {}) {
     const oauth2 = options.oauth2;
+    const kind = options.transport ?? 'auto';
     if (oauth2?.grant === 'authorization_code')
-        return userGrantMcpTools(mcpServerUrl, oauth2, options.tools);
+        return userGrantMcpTools(mcpServerUrl, oauth2, options.tools, kind);
     const tokenSource = oauth2 ? oauthTokenSource(oauth2, `mcp ${mcpServerUrl}`, mcpServerUrl, { allowPrivate: process.env.ALLOW_PRIVATE_MCP === 'true' }) : undefined;
-    let transport;
+    let conn;
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
-        transport = new SSEClientTransport(url, tokenSource
-            ? { fetch: bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)) }
-            : { requestInit: { headers: mcpAuthHeaders(url) }, fetch: mcpFetch });
-        const client = new Client({
-            name: 'melchizedek-a2a-client',
-            version: '1.0.0'
-        }, {
-            capabilities: {}
-        });
-        await client.connect(transport);
-        openTransports.add(transport);
+        conn = tokenSource
+            ? await connectMcp(url, kind, bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)))
+            : await connectMcp(url, kind, mcpFetch, mcpAuthHeaders(url));
+        const client = conn.client;
         // Fetch available tools from the MCP server
         const toolsResponse = await client.listTools();
         return toolsResponse.tools.map((tool) => {
@@ -244,16 +291,18 @@ export async function loadMcpTools(mcpServerUrl, options = {}) {
     catch (error) {
         // A token that cannot be had is reported by kind; the rest as before.
         console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error instanceof ToolCredentialError ? error.message : error);
-        // A failed connect leaves the SSE stream's reconnect timer running; close
-        // it, or every unreachable server keeps retrying for the process's life.
-        if (transport)
-            openTransports.delete(transport);
-        await transport?.close().catch(() => { });
+        // A failed connect closed its own transport (connectMcp); a failed
+        // listing closes this one, or its stream keeps reconnecting for the
+        // process's life.
+        if (conn) {
+            openTransports.delete(conn.transport);
+            await conn.transport.close().catch(() => { });
+        }
         return [];
     }
 }
 /** The tools of a server whose calls carry each user's own OAuth token (authorization_code). */
-function userGrantMcpTools(mcpServerUrl, oauth2, names) {
+function userGrantMcpTools(mcpServerUrl, oauth2, names, kind) {
     const where = `mcp ${mcpServerUrl}`;
     if (!names?.length)
         throw new Error(`${where}: an authorization_code mcp_auth needs mcp_tools, the names this agent may use (no user's grant exists to list them at startup)`);
@@ -286,11 +335,8 @@ function userGrantMcpTools(mcpServerUrl, oauth2, names) {
         conn.holder = holder;
         conn.ready = (async () => {
             const url = await assertSafeMcpUrl(mcpServerUrl);
-            const transport = new SSEClientTransport(url, { fetch: bearerFetch(oauth2, async () => holder.token) });
+            const { client, transport } = await connectMcp(url, kind, bearerFetch(oauth2, async () => holder.token));
             conn.transport = transport;
-            const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
-            await client.connect(transport);
-            openTransports.add(transport);
             if (!listed) {
                 const offered = await client.listTools();
                 for (const tool of offered.tools)

package/dist/lib/tools/mcpTransports.d.ts

@@ -0,0 +1,12 @@
+/**
+ * lib/tools/mcpTransports.ts — the transports an agent may name for an MCP
+ * server (ADR 0124), in a module light enough for the YAML schema to import
+ * without loading the MCP SDK.
+ *
+ * `auto` (the default) posts the initialize request over Streamable HTTP, the
+ * spec's current transport, and falls back to the legacy HTTP+SSE transport
+ * on the spec's signal (lib/tools/mcpToolFactory.ts isSseFallbackSignal);
+ * `streamable_http` and `sse` use that one transport only.
+ */
+export declare const MCP_TRANSPORTS: readonly ['auto', 'streamable_http', 'sse'];
+export type McpTransportKind = (typeof MCP_TRANSPORTS)[number];

package/dist/lib/tools/mcpTransports.js

@@ -0,0 +1,11 @@
+/**
+ * lib/tools/mcpTransports.ts — the transports an agent may name for an MCP
+ * server (ADR 0124), in a module light enough for the YAML schema to import
+ * without loading the MCP SDK.
+ *
+ * `auto` (the default) posts the initialize request over Streamable HTTP, the
+ * spec's current transport, and falls back to the legacy HTTP+SSE transport
+ * on the spec's signal (lib/tools/mcpToolFactory.ts isSseFallbackSignal);
+ * `streamable_http` and `sse` use that one transport only.
+ */
+export const MCP_TRANSPORTS = ['auto', 'streamable_http', 'sse'];

package/dist/lib/tools/oauthConsent.d.ts

@@ -50,10 +50,23 @@ export interface OAuthClientConfig {
     scopes?: string[];
     /** Extra authorization parameters the provider needs (`access_type=offline`, say). Never `state`, `redirect_uri` or the PKCE pair. */
     authorizationParams?: Record<string, string>;
+    /**
+     * The protected resource the token is for (RFC 8707): sent as `resource`
+     * on the authorization request, the code exchange and each refresh. An MCP
+     * server's canonical URI, for a client registered by discovery (ADR 0124).
+     */
+    resource?: string;
 }
+/**
+ * A client found when first needed rather than configured at boot: an MCP
+ * server's authorization server, discovered and registered at
+ * (lib/tools/oauthDiscovery.ts dynamicOAuthClient, ADR 0124). Throws when
+ * it cannot be had; the next call tries again.
+ */
+export type OAuthClientSource = () => Promise<OAuthClientConfig>;
 export interface OAuthConsentOptions {
-    /** Each provider's client, by provider name (lowercase, as the credential store names it). */
-    providers: Record<string, OAuthClientConfig>;
+    /** Each provider's client, by provider name (lowercase, as the credential store names it): configured, or found when first needed. */
+    providers: Record<string, OAuthClientConfig | OAuthClientSource>;
     /**
      * The server's callback URL, exactly as registered at every provider
      * (`https://agents.example.com/oauth/callback`). The A2A server mounts the
@@ -122,7 +135,9 @@ export type ConsentErrorCode =
 /** The grant could not be stored. */
  | 'store_failed'
 /** The provider has no client configured. */
- | 'unknown_provider';
+ | 'unknown_provider'
+/** A discovered client could not be found or registered (ADR 0124). */
+ | 'registration_failed';
 /** A consent step that cannot proceed. The message names the reason, never a value. */
 export declare class ConsentError extends Error {
     readonly code: ConsentErrorCode;