> ## Documentation Index > Fetch the complete documentation index at: https://docs.novaplan.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > PipesHub is a self-hosted enterprise context layer: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations. > When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {PIPESHUB_INSTANCE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline. > Start at https://docs.pipeshub.com/for-agents.md. Client setup: https://docs.pipeshub.com/mcp/overview.md. QM is not an MCP client: https://docs.pipeshub.com/mcp/qm.md. > Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login. > Never print, log, or ask anyone to paste a PipesHub token. # Tools Reference > Tools exposed by the PipesHub MCP server Reference for the tools exposed by the PipesHub MCP server. These tools let an AI client (Cursor, Claude Code, Gemini CLI, Claude.ai, LibreChat, etc.) talk to PipesHub — search and chat over the org's indexed documents, look up people and groups, download files, and talk to configured PipesHub agents. The server exposes **seven** tools. Each one wraps several lower-level API calls so the LLM gets a single, well-shaped response. This page matches the package's [TOOLS.md](https://github.com/pipeshub-ai/mcp-server/blob/main/TOOLS.md). ## `pipeshub_chat` Ask a question and get an answer grounded in the org's indexed sources, with citations. It reads a **few retrieved passages** — never a whole document, never a complete list. | Argument | Type | Required | Description | | ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | yes | The user's question or message for this turn. | | `conversationId` | string | no | Existing conversation id to continue. Omit on the first turn; pass it back on every subsequent turn. | | `filters` | object | no | Source scoping — `{ apps: string[] }` of connector instance UUIDs and/or `knowledgeBase_`. Get ids from `pipeshub_sources`. Only meaningful on the first turn. | | `modelKey` | string | no | Model id from `pipeshub_sources` `llmModels[*].modelKey`. Defaults to the org's default LLM. | | `agentId` | string | no | PipesHub agent to converse with (`agentId` from `pipeshub_agents`). Omit for plain chat. | | `chatMode` | enum | no | Without `agentId`: `internal_search` (default) or `web_search`. With `agentId`, the tool sends `quick` automatically — omit `chatMode`. | **Three questions this tool gets wrong — check them first:** * **Structure** — "what's under this epic?", "which pages are in this space?", "what's in this folder?" → `pipeshub_get_record_content` `mode:"navigate"`. * **Exhaustive** — "how many X?", "list all the Y", "every Z" → `mode:"navigate"`. Chat undercounts and will not say so. * **One named document** — summarize it, extract from it, what does it say about X → `pipeshub_search` for the `recordId`, then `mode:"content"`. Everything else about the org's knowledge belongs here: policies, processes, "what do we know about X", questions spanning several documents. **Response:** the AI's `answer`, `citations[]` (each with `recordId`), `followUpQuestions`, plus the `conversationId` to use for follow-ups. If `citations` is empty, relay the answer as **unsourced and not confirmed**; do not restate its claims as fact. ## `pipeshub_search` Vector / semantic search across the org's indexed documents. Use it to **locate a document** — by name, topic, or a phrase — and to resolve it to a `recordId`. It is also **step 1 of reading a specific document**: search, take the top hit's `recordId`, then call `pipeshub_get_record_content`. | Argument | Type | Required | Description | | -------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `query` | string | yes | Natural language query. | | `limit` | number (1–100) | no | Max number of result chunks. Default 10. Use 5–10 when resolving a filename to a `recordId`. | | `apps` | string\[] | no | Source-scoping ids — connector instance UUIDs and/or `knowledgeBase_`. Get them from `pipeshub_sources`. | **Response:** `hits[]` (`recordId`, `recordName`, `score`, `snippet`, `mimeType`, `webUrl`) sorted by score, plus `uniqueRecords[]` for deduped record-level info. Hits are a ranked sample, never a complete list. Never count them to answer "how many" / "all" / "every"; use `mode:"navigate"` instead. ## `pipeshub_get_record_content` Three operations on records, selected by `mode`. | Argument | Type | Required | Description | | ---------------- | ------------------- | ----------- | -------------------------------------------------------------------------------------------------------- | | `mode` | enum | no | `content` (default), `navigate`, or `lookup`. | | `recordId` | string | conditional | Required when `mode` is `content`. Get it from a chat citation, a search hit, or a `lookup`. | | `nodeId` | string | no | `navigate` only. Omit for a flat listing of everything reachable. | | `page` / `limit` | number | no | `navigate` only. 1-based page, 50–200 children per page (default 50). | | `depth` | number (1–3) | no | `navigate` only. `2` or `3` flattens descendants into one call instead of one call per level. Default 1. | | `identifiers` | string or string\[] | conditional | Required when `mode` is `lookup`. A URL, issue key, or external ID — or up to 10 of them. | * **`mode: "content"`** — the only way to see a document's full text. Use it to summarize, extract, or quote a named document. Prefer it over `pipeshub_download_record` when you need what the record *says* rather than the file bytes. * **`mode: "navigate"`** — browse the hierarchy (project / space / folder → records → children). Use it for structure and for every "how many" / "all" / "every" question. Pass `depth: 2` or `3` to see several levels in one call. Returns no document text. * **`mode: "lookup"`** — resolve a Jira key, URL, or external ID to a `recordId` plus metadata. ## `pipeshub_download_record` Stream the binary content of a single record. Use it when the user wants the actual file bytes (download, attach, open). | Argument | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------- | | `recordId` | string | yes | From a chat citation or `pipeshub_search` hit. | | `convertTo` | string | no | Optional server-side format conversion (e.g. `pdf`). Omit for the original bytes. | ## `pipeshub_directory` Look up people, groups, and teams. One tool with five `action`s. | Argument | Type | Required | Description | | -------- | -------------- | ----------- | ------------------------------------------------------------------------------------- | | `action` | enum | yes | One of `whoami`, `list_users`, `get_user`, `list_groups`, `list_my_teams`. | | `userId` | string | conditional | Required when `action` is `get_user`. | | `page` | number | no | 1-based page number for `list_*` actions. | | `limit` | number (1–100) | no | Items per page for `list_*` actions. | | `search` | string | no | Substring match against name / email. Used by `list_users` (including find-by-email). | ## `pipeshub_sources` Discover available chat sources and AI models in one call. Call this once at the start of a session and cache the result. | Argument | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------------------------------------------- | | `include` | enum\[] | no | Default: `["sources", "llmModels"]`. Add `"embeddingModels"` if configuring re-embedding. | Each source `id` is the value to put in `pipeshub_chat`'s or `pipeshub_search`'s `apps` filter. ## `pipeshub_agents` List the PipesHub **agents** configured for this org. To converse with one, take its `agentId` and pass it to `pipeshub_chat`. **Route on `toolsets` / `knowledge`, not the name.** Match the request to the agent whose tools can actually perform it. The list may be empty — for plain Q\&A, use `pipeshub_chat` without `agentId`. ## Quick Decision Guide | User says... | Use this tool | | --------------------------------------------------- | ----------------------------------------------------------- | | "What does the Q4 report say about ARR?" | `pipeshub_search` → top hit → `pipeshub_get_record_content` | | "Summarize the onboarding doc" | `pipeshub_search` → top hit → `pipeshub_get_record_content` | | "What do we know about X?" (spans many docs) | `pipeshub_chat` | | "What's our PTO policy?" (no single named file) | `pipeshub_chat` | | "How many / list all / every X" | `pipeshub_get_record_content` `mode:"navigate"` — not chat | | "Find the file called *security-review\.pdf*" | `pipeshub_search` | | "Download that file" | `pipeshub_download_record` | | "Who am I?" | `pipeshub_directory` (`whoami`) | | First call of a session | `pipeshub_sources` (cache the result) | | "Create a Jira ticket" / talk to a configured agent | `pipeshub_agents` → `pipeshub_chat` with that `agentId` |