code:read, it also offers the ten pipeshub_code_* tools. Each tool wraps several lower-level API calls so the LLM gets a single, well-shaped response. This page follows the package’s TOOLS.md.
Searching and reading records (
pipeshub_search, then pipeshub_get_record_content) is the recommended default for a client that can call tools. pipeshub_chat is optional: use it when the client cannot run its own search-and-read loop, when you want PipesHub’s own assistant to write the answer, or to talk to a configured agent. On the local server, set PIPESHUB_MCP_CHAT=off to leave it (and pipeshub_agents) out.pipeshub_chat
Optional. Ask PipesHub’s own assistant a question and get an answer grounded in the org’s indexed sources and the live web, with citations. It reads a few retrieved passages, never a whole document or a complete list.
Check these three questions first. Chat gets them wrong:
- Structure: “what’s under this epic?”, “which pages are in this space?”, “what’s in this folder?” →
pipeshub_get_record_contentmode:"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_searchfor therecordId, thenmode:"content".
answer, citations[], claims[], uncitedSentences[], followUpQuestions, plus the conversationId to use for follow-ups. notes[] appears when the tool moved a scoping id to the right list or could not check the ids.
- Each citation has its
number(the[N]in the answer),recordId,recordName,webUrl, and the cited text aspassage(up to 1,500 characters; a longer text is cut and carriespassageTruncated: true).kindsays what the text is:passage,matchedText,summary,recordNameorweb. - Each claim is one cited sentence, with its citation numbers and
quotescopied from the cited text.notInCitedTextlists IDs, numbers or dates the sentence states that none of its cited texts contain. uncitedSentencesare sentences of four or more words with no citation.warningappears if the stream ended early: theansweris then the text received so far and citations are unavailable.
pipeshub_get_record_content mode:"content". If citations is empty, relay the answer as unsourced and not confirmed.
pipeshub_search
Vector / semantic search across the org’s indexed documents. It is the default first step for a question about the org’s knowledge: search, then read the records that matter with pipeshub_get_record_content. It also locates a document by name, topic or phrase and resolves it to a recordId.
Leave out
apps and kb to search everything; if you set either, only the listed sources are searched. The date filters match when a record was written or last changed at its source, not the date of an event it describes, so leave them off unless the question is about when records were written.
Response: records[], one entry per record, best match first: recordId, recordName, recordType, connector, webUrl, createdAt / updatedAt, parent (the channel, space or project it sits in), status (for a ticket or pull request), links (up to 3 related records), score, passagesFound and up to 3 passages (each text is at most 350 characters). Also totalRecords, outsideDates (best matches written outside your date bounds, when a dated search found some) and notes[]. A result stays under 20,000 characters; when records were left out, nextOffset is set.
Records 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
Four operations on records, selected by mode.
mode: "content": The only way to see a document’s full text. Use it to summarize, extract, or quote a named document. A long record comes back in parts, each ending with aRead:line and, while text is left, aNext:line naming the call that reads on. Passquerywithextract: trueto pull a few facts out of a long record for less context.mode: "thread": Every message of the Slack thread thatrecordIdbelongs to, parent first, limited to what the caller may see. A Slack record is one burst of messages; replies are separate records (Reply Count: Nmeans they are not included), so use this mode to read them.mode: "navigate": Browse the hierarchy (project / space / folder → records → children). Use it for structure and for every “how many” / “all” / “every” question. Passdepth: 2or3to see several levels in one call. Returns no document text.mode: "lookup": Resolve a Jira key, URL, or external ID to arecordIdplus metadata.
nodeId, mode: "navigate" lists:
- Whole sources only: the flat listing above, kept to those sources: every record group (project, space, drive, channel) and every record (issue, page, message, file) in them. Its total mixes the two, so don’t read it as a count of issues, pages, messages or files.
- Any space, folder or file picked: one item for each source, space, folder and file picked, and nothing inside them.
pagination.totalcounts these items, not what they hold, anddepthdoes not open them. To see inside an item, pass its id asnodeId. Do that for each item before answering a “how many” or “list all” question.
pipeshub_download_record
Stream the binary content of a single record. Use it when the user wants the actual file bytes (download, attach, open).
pipeshub_directory
Look up people, groups, and teams. One tool with five actions.
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.
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. (toolsets lists the agent’s actions; the API still calls them toolsets.) 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.
Filling a workspace
These tools take an empty workspace to a searchable one.pipeshub_create_collection and pipeshub_upload need the kb:write and kb:upload scopes. pipeshub_add_web_source also needs connector:write and connector:sync. On a new install, personal access tokens and agent logins get all four by default; on an upgraded instance, see Customizing Default Scopes. A token without them is not offered the tools that need them. The local stdio server leaves out every tool that writes with --scope read.
pipeshub_create_collection
Creates an empty collection that the caller owns, to upload into. Names are not unique: to add to an existing collection, use its id from pipeshub_sources.
Returns
{ collectionId, name, url }.
pipeshub_upload
Uploads documents into a collection. Each document travels inline: text for text formats, base64 for binary ones. Up to 20 documents and about 3 MB per call. For a folder or larger files, run the CLI: pipeshub upload <collectionId> <path>, after signing it in with pipeshub login.
Returns
{ uploaded, failed, summary }. Indexing follows in the background.
pipeshub_indexing_status
Reports how far a collection’s or a web source’s records are through indexing. Poll it every 15–30 seconds after an upload or pipeshub_add_web_source until done is true; search finds a document only once it is indexed. Counts are exact at any size.
Returns
{ done, total, pendingCount, failedCount, pending, failed }. done is true only once at least one record is stored, none is still waiting, and the source has finished syncing. A crawl stores its first page a little after it starts and adds pages in batches while it runs, so an early call says done: false, with a note or syncing: true. pending and failed list up to 25 records each, and failed records carry the reason.
pipeshub_connect_source
Returns the page where the user connects Slack, Google Drive, Jira or another source. Connecting needs the user’s own sign-in in a browser, so the agent hands over the link.
Returns
{ url, adminUrl, instructions }. Give the user url: it opens their personal connectors page. adminUrl opens the organization’s connectors page and works only for an admin connecting the source for everyone; anyone else is redirected to their personal page without the connector selected.
pipeshub_add_web_source
Indexes a website, such as a docs site or a public wiki. It sets up a Web connector for the user: it creates the connector, saves the start page and page limit, and starts the crawl. The crawl follows links from the start page and runs again every day. Pages become searchable as they index. Follow them with pipeshub_indexing_status, passing the returned connectorId as collectionId. Connector names are unique and the default is the host name, so a second source on the same site needs its own name. From a terminal: pipeshub add-web <url> [--max-pages <n>] [--name <name>], then pipeshub status <connectorId>.
The other crawl settings keep the Web connector’s defaults:
- It follows links up to 3 clicks from the start page, staying on the same host.
- It finds pages through sitemaps and links.
- It respects
robots.txt.
maxPages, and a site whose robots.txt refuses crawlers stores nothing. The start URL cannot be changed after the source is created.
Returns { connectorId, name, startUrl, maxPages, url }. url opens the user’s connectors page, where the other settings can be changed or the source removed. If a step after the connector is created fails, the error names the connector and links to that page, so the user can finish it there.
Code graph tools
These tools are experimental. They appear only when the caller’s OAuth token or personal access token holds the
code:read scope and the user has at least one indexed code repository. Each checks the caller’s access to every record it returns.
Cross-file call and import edges are resolved for Python, JavaScript, TypeScript and Java; other languages get calls matched by name. A
coverage field in a result says when an answer may be incomplete, so confirm an empty result with pipeshub_search.
Required scopes
offline_access is not a tool scope: it lets the client keep a refresh token. See Customizing Default Scopes.