@zackbart/connecta 0.8.1 → 0.9.1

package/src/errors.ts

@@ -8,6 +8,7 @@ export type ConnectorCallErrorCode =
   | "rate_limited"
   | "unavailable"
   | "invalid_args"
+  | "input_required_unsupported"
   | "connector_call_failed";
 
 /** Agent-visible recovery class attached only to `auth_required` failures. */
@@ -22,6 +23,7 @@ const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
   unavailable: true,
   auth_required: false,
   invalid_args: false,
+  input_required_unsupported: false,
   connector_call_failed: false,
 };
 

package/src/execute.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { ActivityRequestContext } from "./activity.js";
 import {
@@ -150,6 +150,7 @@ export async function buildSandboxProviders(
     maxHostCalls?: number;
     hostCallTimeoutMs?: number;
     discoveryConcurrency?: number;
+    onInvocationFailure?: (failure: InvocationFailure) => void;
   } = {},
 ): Promise<ExecutorProvider[]> {
   // All host calls made by one execute_code invocation share a downstream
@@ -210,7 +211,11 @@ export async function buildSandboxProviders(
       args ?? {},
       invocationContext(),
     );
-    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    if (!outcome.ok) {
+      const failure = new InvocationFailure(outcome.error);
+      limits.onInvocationFailure?.(failure);
+      throw failure;
+    }
     return outcome.value;
   };
   const callNamespace = async (
@@ -225,7 +230,11 @@ export async function buildSandboxProviders(
       args ?? {},
       invocationContext(),
     );
-    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    if (!outcome.ok) {
+      const failure = new InvocationFailure(outcome.error);
+      limits.onInvocationFailure?.(failure);
+      throw failure;
+    }
     return outcome.value;
   };
 
@@ -270,11 +279,20 @@ export async function buildSandboxProviders(
             offset?: number;
             fullDescriptions?: boolean;
             includeSchemas?: "compact" | "json";
+            includeSchemaKeys?: boolean;
           };
-          const result = flatSearchResult(await catalog.search(args));
+          const result = flatSearchResult(
+            await catalog.search({
+              ...args,
+              // Key metadata rides along with schemas by default, since that is
+              // the whole point of it in code mode. It stays opt-out because it
+              // counts against the same hard discovery-byte ceiling.
+              includeSchemaKeys: args.includeSchemaKeys !== false,
+            }),
+          );
           boundedDiscoveryText(
             result,
-            "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+            "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.",
           );
           return result;
         },
@@ -317,6 +335,7 @@ export function createExecuteTool(
     }
     let lease;
     let outcome;
+    const invocationFailures: InvocationFailure[] = [];
     try {
       // Admission comes before provider construction: queued calls retain no
       // catalogs, request scopes, or one-closure-per-tool provider arrays.
@@ -335,6 +354,9 @@ export function createExecuteTool(
         activity,
         {
           signal: controller.signal,
+          onInvocationFailure: (failure) => {
+            invocationFailures.push(failure);
+          },
           ...(config.discoveryConcurrency !== undefined
             ? { discoveryConcurrency: config.discoveryConcurrency }
             : {}),
@@ -386,6 +408,27 @@ export function createExecuteTool(
           )
         : undefined;
     if (outcome.error) {
+      // Executor bridges necessarily reduce thrown host errors to strings.
+      // Match that terminal string back to the request-local typed failure so
+      // an unhandled tool failure keeps the same structured contract as
+      // call_tool and batch_call. Failures caught by model code never reach
+      // outcome.error and therefore remain under that code's control.
+      let invocationFailure: InvocationFailure | undefined;
+      for (let i = invocationFailures.length - 1; i >= 0; i--) {
+        const candidate = invocationFailures[i];
+        if (candidate && outcome.error.includes(candidate.message)) {
+          invocationFailure = candidate;
+          break;
+        }
+      }
+      if (invocationFailure) {
+        const result = jsonResult({
+          error: invocationFailure.details,
+          ...(logs ? { logs } : {}),
+        });
+        result.isError = true;
+        return result;
+      }
       return errorResult(
         `Error: ${outcome.error}${logs ? `\n\nLogs:\n${logs}` : ""}`,
       );
@@ -408,18 +451,18 @@ export function createExecuteTool(
   };
 }
 
-const EXECUTE_DESC = `Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Only tools explicitly annotated readOnlyHint: true are available. For one straightforward call use call_tool; for 2–10 independent calls use batch_call. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
+const EXECUTE_DESC = `Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Never use execute_code for search-only discovery or one downstream call: use search_tools, then call_tool when needed. For 2–10 independent calls use batch_call. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
 - One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from describe_tools. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses.
-- connecta.search(args) and connecta.describe(args) — load and inspect request-local catalogs on demand.
+- connecta.search(args) and connecta.describe(args) — load and inspect request-local catalogs on demand. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the same names the schema shows, ready to check against before building args. They are absent when a schema is not a plain object shape, so read the schema itself rather than assuming a missing list means no fields.
 - console.log(...) — captured and returned alongside the result.
 
 Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
 
-Workflow: search_tools → describe_tools (schemas) → execute_code. Plain JavaScript only — no TypeScript syntax.
-Example: async () => { const r = await crm.search({ query: "roadmap" }); return r.results.map((item) => item.title); }`;
+Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, and continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
+Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((tool) => tool.address.endsWith(suffix)); if (!match) throw new Error("no tool matching " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }`;
 
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(
@@ -448,11 +491,11 @@ export function registerExecuteTool(
     "execute_code",
     {
       description: EXECUTE_DESC,
-      inputSchema: {
+      inputSchema: z.object({
         code: z
           .string()
           .describe("A JavaScript async arrow function to execute."),
-      },
+      }),
       // The sandbox exposes only tools that are explicitly read-only, and the
       // executor grants no network, filesystem, env, or timer capabilities.
       annotations: {
@@ -463,7 +506,7 @@ export function registerExecuteTool(
     },
     async (args, extra) => {
       const controller = new AbortController();
-      const signals = [extra.signal, ctx.requestSignal].filter(
+      const signals = [extra.mcpReq.signal, ctx.requestSignal].filter(
         (signal): signal is AbortSignal => signal !== undefined,
       );
       const forwarders = signals.map((signal) => {

package/src/meta-tools.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type {
   ActivityCallSource,
@@ -611,6 +611,7 @@ export function createMetaTools(
     if (!outcome.ok) {
       const failedResult =
         outcome.error.code === "auth_required" ||
+        outcome.error.code === "input_required_unsupported" ||
         call.resultMode === "value"
           ? jsonResult({
               ok: false,
@@ -620,7 +621,10 @@ export function createMetaTools(
               ...(call.diagnostics ? { timing: outcome.timing } : {}),
             })
           : errorResult(outcome.error.message);
-      if (outcome.error.code === "auth_required") {
+      if (
+        outcome.error.code === "auth_required" ||
+        outcome.error.code === "input_required_unsupported"
+      ) {
         failedResult.isError = true;
       }
       return {
@@ -1114,8 +1118,8 @@ export function createMetaTools(
 
 const LIST_DESC =
   "List connectors with status, cached tool count, and recent real-call health. Use probe=false for a fast inventory; use probe=true (default) only to diagnose live health or authorization.";
-const SEARCH_DESC = `Start here when a tool address is unknown. Exact/name matches rank above description matches; an empty query browses all. The default page has ${DEFAULT_SEARCH_LIMIT} tools; explicit limit can request up to ${MAX_SEARCH_LIMIT}. includeSchemas="compact" usually removes the describe_tools round trip.`;
-const DESCRIBE_DESC = `Inspect up to ${MAX_DESCRIBE_ADDRESSES} known tool addresses when search_tools did not include a sufficient schema. Returns descriptions, input/output schemas, and behavior annotations; format "compact" is the default.`;
+const SEARCH_DESC = `Unknown address: use 2–4 distinctive action/object terms, not the full request; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}) and page only if needed, up to ${MAX_SEARCH_LIMIT}. includeSchemas="compact" adds the input and any declared output shape; matches also carry declared annotations. Call directly when sufficient. Empty query browses all.`;
+const DESCRIBE_DESC = `Only when search_tools omitted schemas, a compact shape is ambiguous, or exact JSON constraints are needed. Inspects up to ${MAX_DESCRIBE_ADDRESSES} addresses with schemas and annotations; "compact" is default, while "json" preserves exact constraints.`;
 const CALL_DESC =
   'Use for one tool explicitly annotated readOnlyHint: true. For 2–10 independent read-only calls use batch_call; for dependent steps or data reduction use execute_code when available. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths, resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
 const CALL_DESTRUCTIVE_DESC =
@@ -1222,7 +1226,7 @@ export function registerMetaTools(
     "skills",
     {
       description: describedFor(registry, SKILLS_DESC, "skills"),
-      inputSchema: { name: z.string().optional() },
+      inputSchema: z.object({ name: z.string().optional() }),
       annotations: READ_ONLY_LOCAL,
     },
     async (args) => mt.skills(args as SkillArgs),
@@ -1232,7 +1236,7 @@ export function registerMetaTools(
     "list_connectors",
     {
       description: LIST_DESC,
-      inputSchema: { probe: z.boolean().optional() },
+      inputSchema: z.object({ probe: z.boolean().optional() }),
       annotations: READ_ONLY_REMOTE,
     },
     async (args) => mt.listConnectors(args as ListArgs),
@@ -1242,14 +1246,14 @@ export function registerMetaTools(
     "search_tools",
     {
       description: describedFor(registry, SEARCH_DESC, "search"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().optional(),
         connector: z.string().optional(),
         limit: z.number().int().positive().max(MAX_SEARCH_LIMIT).optional(),
         offset: z.number().int().nonnegative().optional(),
         fullDescriptions: z.boolean().optional(),
         includeSchemas: z.enum(["compact", "json"]).optional(),
-      },
+      }),
       annotations: READ_ONLY_REMOTE,
     },
     async (args) => mt.searchTools(args as SearchArgs),
@@ -1259,11 +1263,11 @@ export function registerMetaTools(
     "describe_tools",
     {
       description: describedFor(registry, DESCRIBE_DESC, "describe"),
-      inputSchema: {
+      inputSchema: z.object({
         addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
         format: z.enum(["compact", "json"]).optional(),
         fullDescriptions: z.boolean().optional(),
-      },
+      }),
       annotations: READ_ONLY_REMOTE,
     },
     async (args) => mt.describeTools(args as DescribeArgs),
@@ -1273,7 +1277,7 @@ export function registerMetaTools(
     "call_tool",
     {
       description: CALL_DESC,
-      inputSchema: CALL_INPUT_SCHEMA,
+      inputSchema: z.object(CALL_INPUT_SCHEMA),
       // call_tool admits only tools that are themselves explicitly read-only;
       // anything else is refused and routed to call_destructive_tool.
       annotations: READ_ONLY_REMOTE,
@@ -1285,7 +1289,7 @@ export function registerMetaTools(
     "call_destructive_tool",
     {
       description: CALL_DESTRUCTIVE_DESC,
-      inputSchema: CALL_INPUT_SCHEMA,
+      inputSchema: z.object(CALL_INPUT_SCHEMA),
       annotations: {
         destructiveHint: true,
         readOnlyHint: false,
@@ -1299,10 +1303,10 @@ export function registerMetaTools(
     "authorize_connector",
     {
       description: AUTHORIZE_DESC,
-      inputSchema: {
+      inputSchema: z.object({
         connector: z.string(),
         force: z.boolean().optional(),
-      },
+      }),
       // Starts (or with force, resets) a downstream OAuth flow — it changes
       // stored connector auth state, so it is deliberately not read-only.
       annotations: {
@@ -1318,7 +1322,7 @@ export function registerMetaTools(
     "get_result",
     {
       description: GET_RESULT_DESC,
-      inputSchema: {
+      inputSchema: z.object({
         id: z.string(),
         // Both bounds are the shared rules (isValidResultOffset,
         // isValidMaxResultBytes) expressed for the wire: spelling them against
@@ -1326,7 +1330,7 @@ export function registerMetaTools(
         // in-handler checks if either floor ever moves.
         offset: z.number().int().min(MIN_RESULT_OFFSET).optional(),
         maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
-      },
+      }),
       annotations: READ_ONLY_LOCAL,
     },
     async (args) => mt.getResult(args as GetResultArgs),
@@ -1336,7 +1340,7 @@ export function registerMetaTools(
     "batch_call",
     {
       description: BATCH_DESC,
-      inputSchema: {
+      inputSchema: z.object({
         calls: z
           .array(z.object(CALL_INPUT_SCHEMA))
           .min(1)
@@ -1345,7 +1349,7 @@ export function registerMetaTools(
         timeoutMs: z.number().int().positive().optional(),
         maxRetries: z.number().int().min(0).max(2).optional(),
         diagnostics: z.boolean().optional(),
-      },
+      }),
       // Same gate as call_tool: every call in the batch must be explicitly
       // read-only or the batch is refused.
       annotations: READ_ONLY_REMOTE,

package/src/routes/mcp.ts

@@ -1,5 +1,9 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  createMcpHandler,
+  isLegacyRequest,
+  McpServer,
+  WebStandardStreamableHTTPServerTransport,
+} from "@modelcontextprotocol/server";
 import type { ActivityActor, ActivityRequestContext } from "../activity.js";
 import { registerExecuteTool } from "../execute.js";
 import {
@@ -21,7 +25,7 @@ export const MCP_CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
   "Access-Control-Allow-Headers":
-    "Content-Type, Authorization, mcp-protocol-version, mcp-session-id",
+    "Content-Type, Authorization, mcp-protocol-version, mcp-session-id, mcp-method, mcp-name",
 };
 
 // Browser-based MCP clients call /mcp cross-origin. Without CORS on every
@@ -188,54 +192,76 @@ async function serveMcp(
   registry: RegistryView,
   runtimeContext?: RuntimeExecutionContext,
 ): Promise<Response> {
-  // Fresh McpServer + transport per request (SDK ≥1.26 requirement), stateless.
-  const server = new McpServer(opts.serverInfo, {
-    instructions: CONNECTA_INSTRUCTIONS,
-  });
-  const activity: ActivityRequestContext | undefined = opts.activity
-    ? {
-        sink: opts.activity,
-        actor,
-        requestId: crypto.randomUUID(),
-        serverInfo: opts.serverInfo,
-        ...(opts.activityDeploymentId
-          ? { deploymentId: opts.activityDeploymentId }
-          : {}),
-        ...(runtimeContext?.waitUntil
-          ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
-          : {}),
-        logger: opts.logger,
-      }
-    : undefined;
-  registerMetaTools(server, registry, {
-    baseUrl,
-    ...(activity ? { activity } : {}),
-    ...(opts.defaultToolTimeoutMs !== undefined
-      ? { defaultToolTimeoutMs: opts.defaultToolTimeoutMs }
-      : {}),
-    ...(opts.probeTimeoutMs !== undefined
-      ? { probeTimeoutMs: opts.probeTimeoutMs }
-      : {}),
-    ...(opts.discoveryConcurrency !== undefined
-      ? { discoveryConcurrency: opts.discoveryConcurrency }
-      : {}),
-    requestSignal: request.signal,
-    ...(runtimeContext
-      ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
-      : {}),
-  });
-  if (opts.executor) {
-    registerExecuteTool(server, registry, {
+  const createServer = (): McpServer => {
+    const server = new McpServer(opts.serverInfo, {
+      instructions: CONNECTA_INSTRUCTIONS,
+      cacheHints: {
+        "tools/list": {
+          ttlMs: 3_600_000,
+          cacheScope: "private",
+        },
+      },
+    });
+    const activity: ActivityRequestContext | undefined = opts.activity
+      ? {
+          sink: opts.activity,
+          actor,
+          requestId: crypto.randomUUID(),
+          serverInfo: opts.serverInfo,
+          ...(opts.activityDeploymentId
+            ? { deploymentId: opts.activityDeploymentId }
+            : {}),
+          ...(runtimeContext?.waitUntil
+            ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+            : {}),
+          logger: opts.logger,
+        }
+      : undefined;
+    registerMetaTools(server, registry, {
       baseUrl,
-      executor: opts.executor,
-      logger: opts.logger,
       ...(activity ? { activity } : {}),
-      requestSignal: request.signal,
+      ...(opts.defaultToolTimeoutMs !== undefined
+        ? { defaultToolTimeoutMs: opts.defaultToolTimeoutMs }
+        : {}),
+      ...(opts.probeTimeoutMs !== undefined
+        ? { probeTimeoutMs: opts.probeTimeoutMs }
+        : {}),
       ...(opts.discoveryConcurrency !== undefined
         ? { discoveryConcurrency: opts.discoveryConcurrency }
         : {}),
+      requestSignal: request.signal,
+      ...(runtimeContext
+        ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+        : {}),
     });
+    if (opts.executor) {
+      registerExecuteTool(server, registry, {
+        baseUrl,
+        executor: opts.executor,
+        logger: opts.logger,
+        ...(activity ? { activity } : {}),
+        requestSignal: request.signal,
+        ...(opts.discoveryConcurrency !== undefined
+          ? { discoveryConcurrency: opts.discoveryConcurrency }
+          : {}),
+      });
+    }
+    return server;
+  };
+
+  // The v2 entry's built-in legacy fallback streams 2025 results as SSE.
+  // Connecta's established wire contract is JSON, so retain the documented
+  // user-land legacy branch with the same transport setting while the modern
+  // branch uses the fetch-native handler.
+  if (!(await isLegacyRequest(request))) {
+    return createMcpHandler(createServer, {
+      legacy: "reject",
+      onerror: (error) => opts.logger.error("[connecta] MCP handler error", error),
+    }).fetch(request);
   }
+
+  // Fresh server + transport per legacy request, stateless and JSON-shaped.
+  const server = createServer();
   const transport = new WebStandardStreamableHTTPServerTransport({
     enableJsonResponse: true,
   });

package/src/routes/oauth.ts

@@ -309,7 +309,7 @@ export async function routeOAuthCallback(
     return refused();
   }
   try {
-    await connector.finishAuth(code, connectorContext);
+    await connector.finishAuth(code, connectorContext, url.searchParams);
     await opts.registry.invalidateStored(id);
     return html(
       `Connected "${id}". You can close this window.`,

package/src/routes/shared.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Implementation } from "@modelcontextprotocol/server";
 import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity.js";
 import type { CredentialVault } from "../credentials.js";
 import type { DeferredWork } from "../connector-scope.js";
@@ -18,7 +18,7 @@ export interface ServerOptions {
   publicUrl?: string;
   // The SDK's Implementation shape: name/version plus optional title,
   // websiteUrl, and icons (MCP icons spec) that clients may render.
-  serverInfo: ConstructorParameters<typeof McpServer>[0];
+  serverInfo: Implementation;
   logger: Logger;
   activity?: ActivityStore;
   activityReadGate?: ActivityReadGate;

package/src/skills.ts

@@ -1,16 +1,16 @@
 import type { Connector } from "./types.js";
 
 export const CONNECTA_INSTRUCTIONS =
-  'Connecta exposes many integrations behind meta-tools. When an address is unknown, start with search_tools and includeSchemas="compact"; use describe_tools only when that schema is insufficient. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent explicitly read-only calls, and execute_code (when available) only for dependent read-only steps, loops, joins, or reducing large results. Unannotated, write-capable, and destructive tools must use call_destructive_tool individually. Use authorize_connector only after auth_required and get_result only for truncated results. Fetch skills({ name: "usage" }) when this routing workflow is unfamiliar.';
+  'Connecta exposes integrations behind meta-tools. Unknown address: use search_tools with 2–4 distinctive action/object terms, no initial limit, and includeSchemas="compact"; describe_tools only if that shape is ambiguous or exact JSON constraints are needed. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent read-only calls, and execute_code (when available) only for dependencies, loops, joins, or substantial reduction — searching inside that one run rather than searching first. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools. authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 
 export const USAGE_SKILL = `# Connecta usage
 
 ## Choose the smallest execution tool
 
-Use exact addresses returned by discovery; never invent one.
+Use exact addresses returned by discovery; never invent one. Search with 2–4 distinctive action/object terms rather than the full request, and omit \`limit\` initially so the default page stays small.
 
-- Unknown address: \`search_tools({ query, includeSchemas: "compact" })\`.
-- Schema still unclear: \`describe_tools({ addresses: [...] })\`.
+- Unknown address: \`search_tools({ query, includeSchemas: "compact" })\`; every match then includes its input shape plus any declared output shape and annotations.
+- Compact shape still ambiguous: \`describe_tools({ addresses: [...] })\`; use \`format: "json"\` only for exact constraints.
 - One explicitly read-only call: \`call_tool\`.
 - Two to ten independent explicitly read-only calls: \`batch_call\`.
 - Dependent read-only calls, loops, joins, branching, or large-result reduction: \`execute_code\` when available.
@@ -18,15 +18,15 @@ Use exact addresses returned by discovery; never invent one.
 - Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
 - \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
 
-Use \`list_connectors({ probe: false })\` for a fast inventory based on recent call observations and local credential-shape drift. Use \`probe: true\` only when diagnosing live health or authorization.
+Use \`list_connectors({ probe: false })\` for a fast observed-health inventory; use \`probe: true\` only to diagnose live health or authorization.
 
 ## Code mode
 
-Use code mode when calls depend on earlier results, when joining connectors, or when sandbox filtering or aggregation will substantially shrink the response. Use \`Promise.all\` or \`connecta.batch\` for independent calls inside one execution.
+Unknown addresses plus dependent calls: search inside the run, not in an outer \`search_tools\`. Parallelize independent calls with \`Promise.all\` or \`connecta.batch\`.
 
 Connector namespace calls and \`connecta.call\` use the same read-only gate and throw on downstream errors. Catch only failures the workflow can handle; let authorization failures return to the agent for recovery.
 
-Do not use code mode for one call, independent calls already handled by \`batch_call\`, or any tool lacking \`readOnlyHint: true\`. Host calls and time are bounded. Return only the reduced value the agent needs.
+Skip code mode for one call, calls suited to \`batch_call\`, or tools lacking \`readOnlyHint: true\`. Return only the needed reduction.
 `;
 
 /**

package/src/types.ts

@@ -276,8 +276,16 @@ export interface Connector {
    * pending URL could complete consent with their own account.
    */
   verifyState?(state: string | null, ctx: ConnectorContext): Promise<boolean>;
-  /** Optional: complete a downstream OAuth flow (called by /oauth/callback/<id>). */
-  finishAuth?(code: string, ctx: ConnectorContext): Promise<void>;
+  /**
+   * Optional: complete a downstream OAuth flow (called by
+   * /oauth/callback/<id>). `callbackParams` preserves the authorization
+   * server's RFC 9207 `iss` response parameter for SDK validation.
+   */
+  finishAuth?(
+    code: string,
+    ctx: ConnectorContext,
+    callbackParams?: URLSearchParams,
+  ): Promise<void>;
   /**
    * Optional: serve a connector-owned HTTP route — for example a signed
    * download link minted by one of the connector's tools. Called only after

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.8.1";
+export const CONNECTA_VERSION = "0.9.1";