# Use ctxpipe from your agent (https://docs.ctxpipe.ai/docs/mcp/use-from-your-agent) 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](/docs/mcp/mcp-docs). ## 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](/docs/mcp/connected-apps#when-a-tool-says-org_not_found). ## 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 `/:`, 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. ```text 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`. ## Related * [Connect your agent](/docs/mcp/mcp-docs): install and authorize a client * [Connected apps](/docs/mcp/connected-apps): change organizations or revoke a client * [Workspaces](/docs/workspaces): where the knowledge is