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, and download files.
The server exposes five hand-written tools that cover the common PipesHub workflows. Each one wraps several lower-level API calls so the LLM gets a single, well-shaped response.
pipeshub_chat
Default tool for anything PipesHub-related. Ask a question and get a grounded answer with citations from the org’s indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org’s KB, etc.).
| 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 so the server-side history is preserved. |
filters | object | no | Source scoping — { apps: string[] } of connector instance UUIDs and/or knowledgeBase_<orgId>. Get ids from pipeshub_sources. Only meaningful on the first turn. |
modelKey | string | no | Model id from pipeshub_sources models[*].modelKey. Defaults to the org’s default LLM. |
chatMode | enum | no | quick (low-retrieval, fast) or balanced (full RAG). Default quick. |
- “What does document say about X?” →
pipeshub_chat (NOT search — search only locates files).
- “Summarize topic / doc.” →
pipeshub_chat.
- “What’s our policy on Y?” →
pipeshub_chat.
- “Find / locate the file named X” →
pipeshub_search (then pipeshub_download_record if the user wants the bytes).
Response: the AI’s answer, citations[] (each with recordId), followUpQuestions, plus the conversationId to use for follow-ups.
pipeshub_search
Vector / semantic search across the org’s indexed documents. Use this only when the user wants to locate a document — by name, topic, or a phrase to grep for.
| 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_<orgId>. Get them from pipeshub_sources. |
hits[] (recordId, recordName, score, snippet, mimeType, webUrl) sorted by score, plus uniqueRecords[] for deduped record-level info.
For “what does the doc say?” use pipeshub_chat instead — it does the retrieval internally and returns a grounded answer with citations.
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 | Record identifier — UUID for connector-sourced records or 24-char ObjectId for uploaded ones. Get it from a chat citation or pipeshub_search hit. |
convertTo | string | no | Optional server-side format conversion target (e.g. pdf). Omit for the original bytes. |
Content-Type is forwarded from the upstream service. Binary content is base64-encoded; text is inline.
pipeshub_directory
Look up people, groups, and teams in PipesHub. One tool with five actions.
| 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. 24-char ObjectId. |
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. |
whoami — return the authenticated user’s identity (decoded from the bearer JWT). No other args.list_users — paginated list of org users.get_user — full profile for one user (requires userId).list_groups — paginated list of user groups, with userCount.list_my_teams — teams the caller belongs to, with canEdit / canDelete / canManageMembers flags.
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 — sources and models change infrequently.
| Argument | Type | Required | Description |
|---|
include | enum[] | no | Which sections to fetch. Default: ["sources", "llmModels"]. Add "embeddingModels" if configuring re-embedding. |
sources — every connector instance plus the synthetic knowledgeBase_<orgId> entry. Each id is the value to put in pipeshub_chat’s or pipeshub_search’s apps filter.llmModels — chat / generation models. Each modelKey is the value to pass as modelKey to chat/search. Pick isDefault: true unless the user asks for a specific model.embeddingModels — vector embedding models (only when explicitly requested).
Quick Decision Guide
| User says… | Use this tool |
|---|
| ”What does the Q4 report say about ARR?” | pipeshub_chat |
| ”Summarize the onboarding doc” | pipeshub_chat |
| ”What’s our PTO policy?” | pipeshub_chat |
| ”Find the file called security-review.pdf” | pipeshub_search |
| ”Download that file” (after a search or chat citation) | pipeshub_download_record |
| ”Who am I?” / “What’s my user id?” | pipeshub_directory (whoami) |
| “List everyone on the data team” | pipeshub_directory (list_users / list_my_teams) |
| First call of a session, before chat or search | pipeshub_sources (cache the result) |
