Use ctxpipe from your agent

The seven read-only ctxpipe MCP tools, how an agent calls them, and how organizations and Workspaces work.

The ctxpipe MCP gives a coding agent seven read-only tools. The agent does the reasoning and drives the search. ctxpipe returns facts with stable refs, and runs no model for a tool call. To connect a client, see Connect your agent.

The tools

Tool	What it does	Main arguments
`list_workspaces`	Lists the organizations and Workspaces that the connection can read. With one Workspace, it also gives its repositories, sources, and readiness.	`org`, `workspace`
`search_knowledge`	Searches the knowledge with natural language or keywords.	`query`, `workspaces`, `kinds`, `pathPrefix`, `sources`, `updatedAfter`, `validAt`
`search_code`	Searches the linked repositories in one call.	`query`, `mode` (`literal`, `regex`, or `structural`), `repositories`, `language`, `pathGlob`, `caseSensitive`
`find_symbol`	Finds the definition, references, callers, or callees of a symbol.	`symbol`, `relation`, `filePath`, `language`
`read_file`	Reads a knowledge file or a repository file by its ref.	`ref`, `startLine`, `endLine`
`list_files`	Lists the folders and files of a Workspace repository or a linked repository.	`repository`, `path`, `depth`, `glob`
`get_related`	Finds the knowledge near one or more seeds in the graph that is relevant to a question. The results are ranked and explained.	`seeds`, `query`, `intent`, `excludePredicates`, `excludeKinds`

Each tool has the read-only hint. The tools never change your data. The structural mode of search_code needs language. For get_related, intent is one of why, ownership, change, dependencies, structure, provenance, or general.

The server also gives each file as a resource, ctxpipe://{org}/{workspace}/{ref}. A client that supports resources lets you @-mention a file in your prompt.

Organizations and Workspaces

Each call names one organization in the org argument. Use the slug from your ctxpipe URL. Only list_workspaces can leave it out, and then it lists each organization of the connection.
The tools that read one Workspace take its workspace slug. search_knowledge takes a workspaces list. Without a list, it searches all Workspaces of the organization that are ready, up to 8. If the organization has more than 8, name the Workspaces.
When a session starts, the server sends instructions that list your organizations and their Workspaces. In most cases, the agent can call a tool at once.
An organization outside the connection gives org_not_found. See Connected apps.

Refs

A ref is a short, stable name for a result. Use a ref from one tool in another.

A knowledge file ref is its path in the Workspace repository, for example knowledge/services/payments-api.md.
A repository file ref is <owner>/<name>:<path>, for example example/payments-api:src/limits.ts.

Each result shows the branch and the commit that ctxpipe served. ctxpipe serves the default branch of each repository, or the pinned branch or tag.

Exclude the repository that you work in

Your agent works on a local branch with newer files than ctxpipe has. The agent must read that repository from disk, not from ctxpipe. search_code and find_symbol therefore need excludeRepositories: put the URL or the handle of your current repository in it, or send [] to exclude nothing. read_file and list_files take the same list, as an option. A ref into an excluded repository gives excluded_repository.

Good habits for an agent

Search the knowledge before a design choice. Ask for standards, decisions, and owners.
Send calls that do not depend on each other in parallel.
Use search_code, then read_file on the refs that it returns.
Use get_related with a ref that you found, and a query or an intent, to see why a decision was made or who owns a service.
Cite the refs in your answer, and say what still needs a check in the code.

Use ctxpipe before you plan this change. Call list_workspaces, then
search_knowledge for the standards on authentication, and search_code for
the session handling code. Exclude the repository that we work in.

Limits and errors

Each response has a size limit. When a result does not fit, the tool returns one page and a cursor. Send the cursor to get the next page. A cursor stops working when the Workspace changes, and the tool returns stale_cursor. Then search again.
An error has isError: true and { code, message, retryable }.
Each tool needs the ctxpipe:read scope. API keys and the normal OAuth grant have it. A call without it gets 403 insufficient_scope. The MCP tools never need ctxpipe:write.

Connect your agent: install and authorize a client
Connected apps: change organizations or revoke a client
Workspaces: where the knowledge is