@pipeshub-ai/mcp 2.0.1 → 2.2.0

package/src/hooks/request-context.ts

@@ -0,0 +1,47 @@
+/*
+ * Ambient per-tool-call request-id context (AsyncLocalStorage). Mirrors the
+ * pipeshub-ai backend's own request-context pattern (same header name,
+ * `x-request-id`) so a single id traces one MCP tool/resource/prompt
+ * invocation across every backend HTTP call it makes.
+ *
+ * `tools.ts` / `resources.ts` / `prompts.ts` are Speakeasy-generated and
+ * regenerated on every build, so there is no `next()`-style wrapper point to
+ * bind context around a call. Instead `bindNewRequestId` is called from the
+ * hand-written `getClient` closure in `server.ts`, which every generated
+ * dispatch site calls synchronously as the first thing before invoking a
+ * tool/resource/prompt handler — `enterWith` binds the store for the rest of
+ * that handler's execution (sync remainder + everything it awaits).
+ *
+ * The final id (`mcp-<userId>-<random>` or `mcp-<random>`) can't be composed
+ * at bind time — `getClient` only has a `PipeshubCore`, not yet a resolved
+ * `Authorization` header, and resolving security may be async (OAuth2)
+ * while `getClient` must stay sync (generated call sites pass its return
+ * value straight into a handler, never await it). So only the random suffix
+ * is fixed here; `requestid.ts`'s hook fills in `finalId` off the first
+ * outbound request's `Authorization` header and every later call in the
+ * same tool invocation reuses that cached value.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { nanoid } from "nanoid";
+
+export interface RequestContextStore {
+  random: string;
+  finalId?: string;
+}
+
+const storage = new AsyncLocalStorage<RequestContextStore>();
+
+/** Bind a fresh request-id context for the remainder of the current async chain. */
+export function bindNewRequestId(): void {
+  storage.enterWith({ random: nanoid() });
+}
+
+export function getRequestContextStore(): RequestContextStore | undefined {
+  return storage.getStore();
+}
+
+/** One-off id for the rare case a backend call happens with no bound tool-call context. */
+export function newRequestId(): string {
+  return `mcp-${nanoid()}`;
+}

package/src/hooks/requestid.ts

@@ -0,0 +1,62 @@
+/*
+ * Stamp an x-request-id trace header onto every outbound SDK request, reusing
+ * the id bound for the current MCP tool/resource/prompt call (see
+ * request-context.ts) so all backend calls from one invocation share it.
+ *
+ * Format mirrors the TypeScript SDK's own RequestIDHook: `mcp-<userId>-<random>`
+ * when the bearer JWT carries a userId claim, else `mcp-<random>`. The userId
+ * is only knowable once a request actually carries a resolved Authorization
+ * header, so it's decoded off the first outbound request of the tool call and
+ * cached on the bound context for every subsequent call to reuse verbatim.
+ */
+
+import { getRequestContextStore, newRequestId } from "./request-context.js";
+import { BeforeRequestContext, BeforeRequestHook } from "./types.js";
+
+const REQUEST_ID_HEADER = "x-request-id";
+
+/** Decodes the JWT payload without verifying the signature. */
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+  try {
+    const base64Url = token.split(".")[1];
+    if (!base64Url) return null;
+    const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const claims = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    return typeof claims === "object" && claims !== null ? claims : null;
+  } catch {
+    return null;
+  }
+}
+
+function userIdFromRequest(request: Request): string | null {
+  const auth = request.headers.get("authorization") ?? "";
+  if (!auth.toLowerCase().startsWith("bearer ")) return null;
+  const token = auth.slice(7).trim();
+  const claims = decodeJwtPayload(token);
+  return (claims?.["userId"] as string) || null;
+}
+
+export class RequestIDHook implements BeforeRequestHook {
+  beforeRequest(_hookCtx: BeforeRequestContext, request: Request): Request {
+    if (request.headers.get(REQUEST_ID_HEADER)) {
+      return request;
+    }
+
+    const store = getRequestContextStore();
+    if (!store) {
+      // No bound tool-call context (shouldn't happen in practice).
+      request.headers.set(REQUEST_ID_HEADER, newRequestId());
+      return request;
+    }
+
+    if (!store.finalId) {
+      const userId = userIdFromRequest(request);
+      store.finalId = userId
+        ? `mcp-${userId}-${store.random}`
+        : `mcp-${store.random}`;
+    }
+    request.headers.set(REQUEST_ID_HEADER, store.finalId);
+    return request;
+  }
+}

package/src/mcp-server/instructions.ts

@@ -0,0 +1,106 @@
+// Shared routing guidance for the host LLM. Surfaced two ways:
+//   1. As the server `instructions` (always present at `initialize`).
+//   2. As the body of the user-invokable `pipeshub-assistant` prompt.
+// Keeping it in one place avoids the two copies drifting apart.
+
+export const PIPESHUB_INSTRUCTIONS = `# PipesHub MCP — instructions for the LLM
+
+PipesHub is the user's workplace AI platform. It indexes their documents,
+knowledge base content, and connector sources (Drive, Box, Confluence,
+Slack, Jira, Gmail, ...). When in doubt, the answer is in PipesHub.
+
+## Full-document tasks: \`pipeshub_search\` → \`pipeshub_get_record_content\`
+
+\`pipeshub_chat\` answers from a handful of retrieved passages — it never
+reads a whole document. Whenever the task depends on a document's
+COMPLETE content, fetch the document itself:
+
+1. \`pipeshub_search\` with the document's name / topic.
+2. Take the top hit's \`recordId\`.
+3. \`pipeshub_get_record_content\`, and answer from the returned content.
+
+Tasks that need this path — anything where missing part of the document
+could make the answer wrong:
+
+- Summarize / TL;DR / key points / takeaways / action items of a doc.
+- Extract or list ALL of something (dates, owners, requirements, ...).
+- Check whether / where a doc mentions something.
+- Translate, rewrite, outline, review, or reformat a doc.
+- Compare named docs (fetch each \`recordId\`).
+- Any question explicitly scoped to ONE named document — chat retrieval
+  cannot be restricted to a single record.
+
+## Default tool: \`pipeshub_chat\`
+
+**Use \`pipeshub_chat\` for any question that could plausibly be answered
+by the user's PipesHub-indexed data** and is not a full-document task:
+
+- A question that may span several documents, or where you don't yet
+  know which record holds the answer (e.g. "what did Aashil say about
+  onboarding?").
+- Anything about company / org policies, processes, decisions, or
+  history (e.g. "what's our vacation policy?", "who owns the auth
+  service?").
+- Anything explicitly mentioning PipesHub itself, or its sources
+  (Drive / Box / Confluence / Slack / Gmail / Jira / etc.) when the
+  user has those connected.
+- Open-ended "what do we know about X" questions where the answer
+  likely lives in the org's documents.
+
+Do NOT answer those from your own knowledge — \`pipeshub_chat\` grounds
+the answer in the user's actual indexed content and returns citations
+the user can verify.
+
+## When to use the other tools
+
+- \`pipeshub_search\` — locate a document by name or topic and resolve it
+  to a \`recordId\`. To read or summarize one specific document, search,
+  then pass the top hit's \`recordId\` to \`pipeshub_get_record_content\`.
+- \`pipeshub_download_record\` — when the user wants the actual file
+  bytes (download, attach, open). Get the \`recordId\` either from
+  citations on a prior \`pipeshub_chat\` response or from
+  \`pipeshub_search\`.
+- \`pipeshub_get_record_content\` — when you need a record's full parsed
+  content (returned as a single \`content\` string: metadata header plus
+  the document's text) without downloading the original file. Prefer this
+  over download when the question is about what the record says.
+- \`pipeshub_directory\` — people, groups, teams, and \`whoami\` lookups.
+  Not for documents.
+- \`pipeshub_sources\` — call once at the start of a session to discover
+  which connectors / KB / models are available, then cache the result.
+- \`pipeshub_agents\` — list the org's configured **agents** (specialized
+  assistants with their own prompt, tools, and knowledge scope).
+
+## Agents
+
+Some orgs configure **agents** for specific jobs (e.g. a Slack messenger, a
+Jira ticket creator, a Salesforce CRM updater). To run a turn against an
+agent, call \`pipeshub_chat\` with its \`agentId\` (from \`pipeshub_agents\`)
+— optionally with an agent \`chatMode\` (\`auto\` by default, or \`quick\` /
+\`verification\` / \`deep\`). Keep passing the same \`agentId\` plus the
+returned \`conversationId\` on follow-up turns.
+
+**When to route to an agent vs plain chat:**
+- The user names a system/action that maps to an agent (e.g. "post to
+  Slack", "create a Jira ticket", "update the Salesforce deal") → call
+  \`pipeshub_agents\`, pick the matching agent, and use it.
+- Plain question about the org's knowledge or the public web → just use
+  \`pipeshub_chat\` (no \`agentId\`) with \`internal_search\` or \`web_search\`.
+
+**If you are unsure which agent or route fits the request**, call
+\`pipeshub_agents\` FIRST and read the returned names/descriptions, then
+either pick the best match or present the list to the user and let them
+choose. Do NOT guess an agent blindly, and do NOT refuse — list the agents
+and decide from real data. The list may be empty (no agents configured),
+in which case fall back to plain \`pipeshub_chat\`.
+
+## Conversation lifecycle
+
+\`pipeshub_chat\` is a single tool that handles both starting and
+continuing conversations (plain or with an \`agentId\`). On the first turn
+omit \`conversationId\`; on every subsequent turn pass back the
+\`conversationId\` returned by the previous call (along with the same
+\`agentId\` if you used one). Server-side context is preserved — do NOT
+replay prior messages. Only start a fresh conversation when the user
+explicitly asks to clear context.
+`;

package/src/mcp-server/prompts/pipeshubAssistant.ts

@@ -0,0 +1,37 @@
+import * as z from "zod";
+import { PromptDefinition } from "../prompts.js";
+import { PIPESHUB_INSTRUCTIONS } from "../instructions.js";
+
+const args = {
+  query: z.string().optional().describe(
+    "Optional. The user's request to route. Provide it to have the guidance "
+      + "applied to a concrete request; omit it to just load the routing "
+      + "guidance as a seed system prompt at the start of a session.",
+  ),
+};
+
+export const prompt$pipeshubAssistant: PromptDefinition<typeof args> = {
+  name: "pipeshub-assistant",
+  description:
+    "Load PipesHub tool-routing guidance so the assistant picks the correct "
+    + "tool (pipeshub_chat / search / agents / directory) and lists agents "
+    + "with pipeshub_agents when unsure which route fits the query.",
+  scopes: ["read"],
+  args,
+  prompt: (_client, args, _extra) => {
+    const text = args.query
+      ? `${PIPESHUB_INSTRUCTIONS}\n\n---\n\nFollow the routing rules above to `
+        + `handle this request, picking the right tool (and listing agents via `
+        + `\`pipeshub_agents\` if unsure which route fits):\n\n${args.query}`
+      : PIPESHUB_INSTRUCTIONS;
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text },
+        },
+      ],
+    };
+  },
+};

package/src/mcp-server/server.ts

@@ -1,66 +1,8 @@
-// Hand-written; replaces the Speakeasy-generated server.ts. Registers the
-// five curated PipesHub tools instead of one tool per OpenAPI operation.
-
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
-// Top-level instructions surfaced to the host LLM at server initialize.
-// These set defaults so the model picks `pipeshub_chat` as the natural
-// entry point for anything that touches the user's PipesHub data —
-// documents, files, knowledge base content, citations, etc.
-const PIPESHUB_INSTRUCTIONS = `# PipesHub MCP — instructions for the LLM
-
-PipesHub is the user's workplace AI platform. It indexes their documents,
-knowledge base content, and connector sources (Drive, Box, Confluence,
-Slack, Jira, Gmail, ...). When in doubt, the answer is in PipesHub.
-
-## Default tool: \`pipeshub_chat\`
-
-**Use \`pipeshub_chat\` for any question that could plausibly be answered
-by the user's PipesHub-indexed data.** That includes:
-
-- Anything about a specific document, file, report, ticket, message, or
-  page (e.g. "what's in the Q4 sales report?", "summarize the langchain
-  doc", "what did Aashil say about onboarding?").
-- Anything about company / org policies, processes, decisions, or
-  history (e.g. "what's our vacation policy?", "who owns the auth
-  service?").
-- Anything explicitly mentioning PipesHub itself, or its sources
-  (Drive / Box / Confluence / Slack / Gmail / Jira / etc.) when the
-  user has those connected.
-- Open-ended "what do we know about X" questions where the answer
-  likely lives in the org's documents.
-
-Do NOT answer those from your own knowledge — \`pipeshub_chat\` grounds
-the answer in the user's actual indexed content and returns citations
-the user can verify.
-
-## When to use the other tools
-
-- \`pipeshub_search\` — only when the user asks specifically to **find /
-  locate** a document by name or topic (so you can hand them a list, or
-  resolve a filename to a \`recordId\` for download). For "what does
-  the doc say?" use \`pipeshub_chat\` instead — it does the retrieval
-  internally.
-- \`pipeshub_download_record\` — when the user wants the actual file
-  bytes (download, attach, open). Get the \`recordId\` either from
-  citations on a prior \`pipeshub_chat\` response or from
-  \`pipeshub_search\`.
-- \`pipeshub_directory\` — people, groups, teams, and \`whoami\` lookups.
-  Not for documents.
-- \`pipeshub_sources\` — call once at the start of a session to discover
-  which connectors / KB / models are available, then cache the result.
-
-## Conversation lifecycle
-
-\`pipeshub_chat\` is a single tool that handles both starting and
-continuing conversations. On the first turn omit \`conversationId\`; on
-every subsequent turn pass back the \`conversationId\` returned by the
-previous call. Server-side context is preserved — do NOT replay prior
-messages. Only start a fresh conversation when the user explicitly
-asks to clear context.
-`;
-
+import { PIPESHUB_INSTRUCTIONS } from "./instructions.js";
 import { PipeshubCore } from "../core.js";
+import { bindNewRequestId } from "../hooks/request-context.js";
 import { SDKOptions } from "../lib/config.js";
 import type { ConsoleLogger } from "./console-logger.js";
 import { createRegisterPrompt } from "./prompts.js";
@@ -73,8 +15,11 @@ import { createRegisterTool, registerDynamicTools } from "./tools.js";
 import { tool$pipeshubChat } from "./tools/pipeshubChat.js";
 import { tool$pipeshubSearch } from "./tools/pipeshubSearch.js";
 import { tool$pipeshubDownloadRecord } from "./tools/pipeshubDownloadRecord.js";
+import { tool$pipeshubGetRecordContent } from "./tools/pipeshubGetRecordContent.js";
 import { tool$pipeshubDirectory } from "./tools/pipeshubDirectory.js";
 import { tool$pipeshubSources } from "./tools/pipeshubSources.js";
+import { tool$pipeshubAgents } from "./tools/pipeshubAgents.js";
+import { prompt$pipeshubAssistant } from "./prompts/pipeshubAssistant.js";
 
 export function createMCPServer(deps: {
   logger: ConsoleLogger;
@@ -97,7 +42,7 @@ export function createMCPServer(deps: {
     },
   );
 
-  const getClient = deps.getSDK || (() =>
+  const resolveClient = deps.getSDK || (() =>
     new PipeshubCore({
       security: deps.security,
       serverURL: deps.serverURL,
@@ -112,6 +57,11 @@ export function createMCPServer(deps: {
         : undefined,
     }));
 
+  const getClient = () => {
+    bindNewRequestId();
+    return resolveClient();
+  };
+
   const scopes = new Set(deps.scopes);
 
   const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
@@ -139,13 +89,17 @@ export function createMCPServer(deps: {
   const register = { tool, resource, resourceTemplate, prompt };
   void register; // suppress unused warnings
 
-  // Curated tool set. Five tools instead of ten one-per-op generated tools.
-  // Order = preferred discovery order shown to the LLM.
+  // Curated tool set. Order = preferred discovery order shown to the LLM.
   tool(tool$pipeshubSources);          // 1. discover sources + models
   tool(tool$pipeshubChat);             // 2. ask questions (start + continue)
   tool(tool$pipeshubSearch);           // 3. resolve filename → recordId
   tool(tool$pipeshubDownloadRecord);   // 4. fetch a document by id
-  tool(tool$pipeshubDirectory);        // 5. people / groups / teams / whoami
+  tool(tool$pipeshubGetRecordContent); // 5. fetch a record's parsed content
+  tool(tool$pipeshubDirectory);        // 6. people / groups / teams / whoami
+  tool(tool$pipeshubAgents);           // 7. discover org agents
+
+  // Curated prompt: user-invokable tool-routing guidance.
+  prompt(prompt$pipeshubAssistant);
 
   if (deps.dynamic) {
     registerDynamicTools(deps.logger, server, getClient, toolMap, scopes);

package/src/mcp-server/tools/_helpers.ts

@@ -1,12 +1,17 @@
-// Curated-tool helpers. Hand-written, NOT regenerated by Speakeasy.
 //
 // Each curated tool fetches a Response from one of the SDK funcs and then
 // trims / restructures the body before handing it to the LLM. The helpers
 // here keep that work out of the individual tool files.
 
+import * as z from "zod";
 import { Security } from "../../models/security.js";
 import { PipeshubCore } from "../../core.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { agentsListAgents } from "../../funcs/agentsListAgents.js";
+import {
+  AgentListEnvelope$zodSchema,
+  AgentSummary,
+} from "../../models/agentops.js";
 
 /**
  * Parse a fetch Response as JSON, returning a CallToolResult error when the
@@ -58,6 +63,94 @@ export function errorResult(message: string): CallToolResult {
   };
 }
 
+/**
+ * Guard a (possibly streaming) `Response` on its HTTP status. The streaming
+ * SDK funcs configure `errorCodes: []`, so the request layer treats ANY HTTP
+ * response — including 401 / 403 / 404 / 5xx — as a success and hands back the
+ * raw `Response`. Without this check those failures slip into the SSE drain
+ * and surface as the useless "stream ended without usable frames".
+ *
+ * Returns a `CallToolResult` error (status + best-effort message from the body)
+ * when the response is not ok, or `null` when it is ok (body left untouched so
+ * the caller can still stream it).
+ */
+export async function httpErrorResult(
+  response: Response,
+  context: string,
+): Promise<CallToolResult | null> {
+  if (response.ok) return null;
+
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    // body unreadable (e.g. already-consumed or transport error)
+  }
+
+  let message: string = body;
+  if (body) {
+    try {
+      const parsed = JSON.parse(body);
+      // Only accept string fields — error envelopes often nest an object
+      // under `error`, which must not stringify to "[object Object]".
+      const candidate =
+        (typeof parsed?.message === "string" && parsed.message)
+        || (typeof parsed?.error === "string" && parsed.error)
+        || (typeof parsed?.error?.message === "string" && parsed.error.message)
+        || (typeof parsed?.detail === "string" && parsed.detail)
+        || "";
+      message = candidate || body; // fall back to the raw JSON text
+    } catch {
+      // not JSON — keep the raw text
+    }
+  }
+
+  const detail = message ? ` ${message.slice(0, 400)}` : "";
+  const auth = (response.status === 401 || response.status === 403)
+    ? " Check that the bearer token / credentials are valid and not expired."
+    : "";
+  return errorResult(
+    `${context} failed (HTTP ${response.status} ${response.statusText}).${detail}${auth}`,
+  );
+}
+
+/**
+ * Read a `Response` body as JSON and validate it against a zod `schema`,
+ * returning the typed value or a `CallToolResult` error (empty body, invalid
+ * JSON, or a shape that doesn't match the schema).
+ */
+export async function readValidated<T>(
+  response: Response,
+  schema: z.ZodType<T>,
+): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  const text = await response.text();
+  if (!text) {
+    return { ok: false, result: errorResult("Empty response from server") };
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (e) {
+    return {
+      ok: false,
+      result: errorResult(
+        `Failed to parse response as JSON: ${(e as Error).message}`
+          + `\n\nRaw body:\n${text.slice(0, 500)}`,
+      ),
+    };
+  }
+  const parsed = schema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      result: errorResult(
+        `Unexpected response shape:\n${z.prettifyError(parsed.error)}`,
+      ),
+    };
+  }
+  return { ok: true, value: parsed.data };
+}
+
 /** Resolve `client._options.security` (which may be a function) to a value. */
 export async function resolveSecurity(
   client: PipeshubCore,
@@ -257,6 +350,128 @@ export async function* iterateSSE(
   }
 }
 
+// ── Trimmed agent shape handed to the LLM ────────────────────────────────────
+
+interface AgentToolsetView {
+  /** Integration / connector key, e.g. `jira`, `gmail`. */
+  name: string | null | undefined;
+  /** Fully-qualified tool ids the agent can run, e.g. `jira.create_issue`. */
+  tools: string[];
+}
+
+interface AgentKnowledgeView {
+  name: string | null | undefined;
+  type: string | null | undefined;
+}
+
+export interface EnrichedAgent {
+  agentId: string;
+  name: string;
+  description: string | null;
+  systemPrompt: string | null;
+  startMessage: string | null;
+  tags: string[];
+  webSearch: boolean;
+  isActive: boolean | null | undefined;
+  toolsets: AgentToolsetView[];
+  knowledge: AgentKnowledgeView[];
+}
+
+/**
+ * Trim an enriched `AgentSummary` (from `GET /agents`) to just what the LLM
+ * needs to pick and converse with an agent. Strips ids/revs/timestamps/perms
+ * and the heavy nested tool/knowledge metadata, keeping the routing-critical
+ * signal: each toolset's connector `name` + its tool ids (e.g.
+ * `jira.create_issue`), and each knowledge source's `name`/`type`.
+ */
+export function trimAgent(a: AgentSummary): EnrichedAgent {
+  return {
+    agentId: a._key,
+    name: a.name,
+    description: a.description ?? null,
+    systemPrompt: a.systemPrompt ?? null,
+    startMessage: a.startMessage ?? null,
+    tags: a.tags,
+    webSearch: !!a.webSearch,
+    isActive: a.isActive,
+    toolsets: a.toolsets.map((ts) => ({
+      name: ts.name,
+      tools: ts.tools
+        .map((t) => t.fullName ?? t.name)
+        .filter((id): id is string => typeof id === "string"),
+    })),
+    knowledge: a.knowledge.map((k) => ({
+      name: k.name ?? k.displayName,
+      type: k.type,
+    })),
+  };
+}
+
+/**
+ * Fetch the COMPLETE agent list, auto-paginating `GET /agents` so callers
+ * (discovery + routing) never have to manage page numbers. Pages are fetched
+ * at the max page size until the backend reports no more (`hasNext` /
+ * `hasNextPage`, with a short-page fallback), capped by `maxPages` as a
+ * runaway guard. Returns the raw `AgentListItem`s plus a normalized `total`
+ * and a `truncated` flag (true if the cap was hit before exhausting pages).
+ */
+export async function listAllAgents(
+  client: PipeshubCore,
+  opts: {
+    search?: string | undefined;
+    signal?: AbortSignal | undefined;
+    maxPages?: number | undefined;
+  } = {},
+): Promise<
+  | { ok: true; agents: AgentSummary[]; total: number; truncated: boolean }
+  | { ok: false; result: CallToolResult }
+> {
+  const PAGE_SIZE = 200;
+  const maxPages = opts.maxPages ?? 25;
+  // Only set `signal` when present (exactOptionalPropertyTypes).
+  const reqOptions = opts.signal
+    ? { fetchOptions: { signal: opts.signal } }
+    : {};
+
+  const all: AgentSummary[] = [];
+  let total = 0;
+
+  for (let page = 1; page <= maxPages; page++) {
+    const [r] = await agentsListAgents(client, {
+      page,
+      limit: PAGE_SIZE,
+      search: opts.search,
+    }, reqOptions).$inspect();
+    if (!r.ok) return { ok: false, result: errorResult(r.error.message) };
+
+    const httpErr = await httpErrorResult(r.value, "Agent list request");
+    if (httpErr) return { ok: false, result: httpErr };
+
+    const parsed = await readValidated(r.value, AgentListEnvelope$zodSchema);
+    if (!parsed.ok) return { ok: false, result: parsed.result };
+    if (parsed.value.success === false) {
+      return {
+        ok: false,
+        result: errorResult("Agent list request returned success: false"),
+      };
+    }
+
+    const agents = parsed.value.agents;
+    all.push(...agents);
+
+    const pg = parsed.value.pagination;
+    total = pg?.totalItems ?? pg?.total ?? all.length;
+
+    const hasNext = pg?.hasNext ?? pg?.hasNextPage ?? (agents.length >= PAGE_SIZE);
+    if (!hasNext || agents.length === 0) {
+      return { ok: true, agents: all, total, truncated: false };
+    }
+  }
+
+  // Hit the page cap with more pages still available.
+  return { ok: true, agents: all, total: total || all.length, truncated: true };
+}
+
 /** Trim a single search hit to what the LLM actually needs. */
 export function trimSearchHit(hit: any) {
   const md = hit?.metadata ?? {};

package/src/mcp-server/tools/pipeshubAgents.ts

@@ -0,0 +1,68 @@
+// (`GET /agents`) — each already carrying its `toolsets` and `knowledge` — so
+// the LLM can route on real capability rather than the often-generic
+// description. Pick an agent's `agentId` and pass it to `pipeshub_chat`'s
+// `agentId` to converse with it. Single API call, no per-agent fan-out.
+
+import * as z from "zod";
+import { ToolDefinition } from "../tools.js";
+import { jsonResult, listAllAgents, trimAgent } from "./_helpers.js";
+
+const args = {
+  search: z.string().optional().describe(
+    "Optional case-insensitive substring match across agent name, "
+      + "description, and tags. Omit to return every agent.",
+  ),
+};
+
+export const tool$pipeshubAgents: ToolDefinition<typeof args> = {
+  name: "pipeshub_agents",
+  description:
+    `List the PipesHub **agents** configured for this org, each with its
+capabilities.
+
+Agents are specialized assistants (custom system prompt, tools, knowledge
+scope). To converse with one, take its \`agentId\` and pass it to
+\`pipeshub_chat\`'s \`agentId\` argument.
+
+Each agent is returned as:
+\`{ agentId, name, description, systemPrompt, startMessage, tags, webSearch,
+isActive, toolsets, knowledge }\`.
+- \`toolsets\` — what the agent can DO: each \`{ name, tools }\` where \`name\`
+  is the connector (e.g. \`jira\`, \`gmail\`) and \`tools\` are the runnable
+  tool ids (e.g. \`jira.create_issue\`, \`gmail.send_email\`).
+- \`knowledge\` — what the agent can READ: each \`{ name, type }\` (e.g.
+  \`Confluence-2\` / \`Confluence\`).
+
+**Route on \`toolsets\`/\`knowledge\`, not the name** — names and descriptions
+are often generic or misleading. Match the request to the agent whose tools can
+actually perform it (e.g. "create a Jira ticket" → the agent whose toolset is
+\`jira\` and whose tools include \`jira.create_issue\`). If NO agent has a tool
+for the requested action, say so — don't force an unrelated agent.
+
+The list **may be empty** (no agents configured). For plain Q&A when no
+specific agent is needed, use \`pipeshub_chat\` WITHOUT \`agentId\` and pick a
+\`chatMode\`: \`internal_search\` (org's indexed knowledge) or \`web_search\`
+(live web). Use \`agentId\` everywhere an agent is referenced.`,
+  scopes: ["read"],
+  annotations: {
+    title: "List PipesHub agents (with toolsets & knowledge)",
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const all = await listAllAgents(client, {
+      search: args.search,
+      signal: ctx.signal,
+    });
+    if (!all.ok) return all.result;
+
+    return jsonResult({
+      agents: all.agents.map(trimAgent),
+      total: all.total,
+      ...(all.truncated ? { truncated: true } : {}),
+    });
+  },
+};