# pipelex-mcp

<!-- onboarding: workshop-route -->
<!-- Generated from the Pipelex onboarding source; this region is replaced from https://raw.githubusercontent.com/Pipelex/.github/main/onboarding/rendered/workshop-route.md — do not edit it here. -->
## Get started

Pipelex lets you build AI methods with your coding agent and run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software. This repository holds the Pipelex tools, which your coding agent gets with the Pipelex plugin: they run your methods and also work with the method files in your project.

**1. Sign up at [app.pipelex.com](https://app.pipelex.com).**

**2. Install the Pipelex plugin in your coding agent.** The plugin gives your agent the skills that build methods, run them and put them in your software, a hook that checks every edit, and the Pipelex tools.

<details open><summary><b>Claude Code</b></summary>

```bash
claude plugin marketplace add Pipelex/pipelex-plugins
claude plugin install pipelex@pipelex-plugins
```

Claude Code asks for an API key when you enable the plugin, and stores it in your OS keychain — create one in your console at [app.pipelex.com](https://app.pipelex.com). The skills, the hook that checks every edit and the Pipelex tools load with it. The plugin's hook and the Pipelex tools run on Node.js, so you need Node.js on your `PATH`.

Claude Code also loads what you have added to your Claude account, so if you added the Pipelex MCP to Claude, Claude Code has it too. An agent with the plugin does not need the Pipelex MCP, and there is nothing to turn off: when both are present, the Pipelex MCP defers to the plugin's tools.

</details>

<details open><summary><b>Codex</b></summary>

```bash
codex plugin marketplace add Pipelex/pipelex-plugins
export PIPELEX_API_KEY=plx_sk_...     # create one in your console at app.pipelex.com
```

Restart Codex, run `/plugins` to install `pipelex`, and trust the plugin hook on first run. Requires Codex 0.141 or later. The plugin's hook and the Pipelex tools run on Node.js, so you need Node.js on your `PATH`.

</details>

**3. Ask your agent for the method you want.**

> Design a method that reads an invoice PDF and returns the supplier, the total and the line items. Then run it on `~/Downloads/invoice.pdf` and save it to my Pipelex account.

`/pipelex-design` writes the method, the hook checks it on every edit, `/pipelex-run` starts it and prints a run id you can come back to, and `/pipelex-catalog` saves it to your account, where your chatbot can run it too.

**Chatbots** — ChatGPT, Claude — take the Pipelex MCP instead, a connector for chatbots that this repository does not hold: add it in your chatbot's settings by its address, `https://mcp.pipelex.com/mcp`.

Other hosts, and the reference for developers, start at [Which server, for which host](#which-server-for-which-host).

**Next:** [what Pipelex is](https://go.pipelex.com/product) · [documentation](https://go.pipelex.com/docs) · [your console](https://app.pipelex.com) · [Discord](https://go.pipelex.com/discord)
<!-- /onboarding -->

## Which server, for which host

A host needs one of two things, not both: the Pipelex plugin on a coding agent, the Pipelex MCP on a chatbot. The table applies that rule host by host. [You don't need both](#you-dont-need-both) says what happens when the Pipelex MCP added in Claude reaches Claude Code without anyone choosing it.

| Host | Tool | How to connect |
|---|---|---|
| Claude Code | Pipelex plugin | [Install the plugin](https://github.com/Pipelex/pipelex-plugins#quick-start) |
| Codex | Pipelex plugin | [Install the plugin](https://github.com/Pipelex/pipelex-plugins#quick-start) |
| ChatGPT (web) | Pipelex MCP | A developer-mode app, created by the address above ([OpenAI's conditions](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)) |
| claude.ai (web + mobile) | Pipelex MCP | **Add custom connector**, by the address above |
| Claude Desktop | Pipelex MCP | **Add custom connector**, by the address above |

A host that spawns MCP servers but takes no plugin, such as Cursor, can run the plugin's MCP server by hand: [Registering the workshop in a host](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/hosts.md) gives its configuration.

## What this repository is

This repository is **the workshop**, the MCP server inside the Pipelex plugin (server name `pipelex-plugin`): an npm-distributed stdio server (`@pipelex/mcp`, bin `pipelex-mcp`) that coding-agent hosts spawn via `npx`. It wraps the Pipelex API through the `@pipelex/sdk` `PipelexApiClient`. Its tools are `mthds_*`: they find a saved method and the files your organization holds, validate a method, template its inputs, generate typed code for it, prepare its files, run it, look up the model references it can name, save it to the catalog as a draft and pull it back, and publish the draft as a version when you ask. Its headline feature is reading methods from disk instead of having the model hand-copy their contents: a method's folder, given as `method_dir`, or its files, given as `{ path }` items. It is **tools-first and ships no views on any host**, so it reports structured results and text summaries directly.

The Pipelex MCP for chatbots, at `mcp.pipelex.com`, is the hosted Pipelex connector, a separate product with tools of its own, named `pipelex_*`: see [Chat hosts use the Pipelex connector](#chat-hosts-use-the-pipelex-connector).

## Tools

[The tools reference](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md) gives each tool's input, result and behavior.

| Tool | What it does |
|---|---|
| [`mthds_list_methods`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_list_methods) | List the methods saved in your organization's catalog by name, description and id, never their source. |
| [`mthds_list_files`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_list_files) | List the files your organization holds, uploads, a method's test files and runs' outputs, each with the address a run's inputs take with nothing to upload. |
| [`mthds_models`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_models) | List the model references a pipe can name, or check one before writing it into a method. |
| [`mthds_validate`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_validate) | Validate a method given as its folder, files, a published address or a catalog id, return its main pipe's typed signature, and write its flowchart as an HTML page beside a method on disk. |
| [`mthds_inputs_template`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_inputs_template) | Return a fill-in template of a pipe's declared inputs. |
| [`mthds_codegen`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_codegen) | Generate typed TypeScript or Python for a method's concepts, stamped and locked, returned or written straight to disk. |
| [`mthds_prepare_inputs`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_prepare_inputs) | Make filled inputs run-ready, uploading local files to Pipelex storage as your organization's files or as a method's test files. |
| [`mthds_run`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_run--mthds_run_status--mthds_run_results) | Start a durable run on the hosted Pipelex API from a folder, files, an address or an id, and return its `run_id` at once. |
| [`mthds_run_status`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_run--mthds_run_status--mthds_run_results) | Read a run's lifecycle state and how far it has got by its `run_id`. |
| [`mthds_run_results`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_run--mthds_run_status--mthds_run_results) | Fetch a run's outcome, and list for free which of its stored files look like images. |
| [`mthds_show_images`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_show_images) | Show the pictures a completed run produced, as image content that stays in the conversation. |
| [`mthds_download_artifacts`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_download_artifacts) | Save a completed run to disk: its output as `main_stuff.json`, and the files it produced. |
| [`mthds_save_method`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_save_method--mthds_get_method--mthds_publish_method) | Validate a method's folder and save its whole tree as the method's draft in your organization's catalog, linking the folder to the saved method in `.pipelex/method.json`. A save never publishes. |
| [`mthds_get_method`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_save_method--mthds_get_method--mthds_publish_method) | Bring a saved method's draft, or one of its published versions, back, its whole tree to disk or its text files inline. |
| [`mthds_publish_method`](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#mthds_save_method--mthds_get_method--mthds_publish_method) | Publish a method's draft as its next version, which callers of its bare id then run, when you ask for a publish. |

## Files on the workshop, by path

MCP tool arguments are generated token-by-token by the host LLM — there is no other channel from the conversation to the server. So submitting a bundle's `.mthds` contents inline means the model re-emits every file as output tokens (slow on large bundles, re-paid every repair-loop iteration and every tool in the chain, and not guaranteed byte-identical to what's on disk). The workshop sidesteps this: the host spawns it in your workspace, so it can read files from disk given only a path.

The workshop's files-taking tools accept two item forms — inline content or a file path:

```ts
type SubmittedFileInput = { content: string; uri?: string | null } | { path: string };
```

The workshop reads `{ path }` items from disk before invoking the capability — near-constant token cost regardless of the method's size, byte-accurate reads, and real provenance (each file is sent under its path in the method's tree, so diagnostics locate to files you can open and edit). Inline `{ content, uri? }` items stay accepted, for a `.mthds` file the agent holds only in the conversation. An item is one arm or the other; on a malformed item carrying both keys, `content` wins (first-match union semantics) and `path` is ignored.

**A method's folder.** For a method on disk, the method-taking tools take its folder as `method_dir` instead of a file list. The workshop sends the folder's whole tree, the same tree `mthds_save_method` saves: its `.mthds` files, its templates, its Python modules and its data, and lists every file it sent in the result. Which files belong to it is the MTHDS standard's rule: files whose path has a segment starting with a dot, `__pycache__/` and `node_modules/` directories, Python virtual environments, nested repositories and packages, and whatever a `.gitignore` inside the folder excludes are not part of it, nor is a run's `inputs.json` or `inputs.toml`, and a symbolic link is refused. The folder must sit inside the working directory and hold a `.mthds` file at its top, and its tree is held to the limits the Pipelex deployment announces. The [tool reference](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#the-tools) has the rule.

**A list of files is one tree too.** The `{ path }` items keep where they sit relative to one another: the tree is rooted at the deepest directory holding them all, or at the working directory when the list also holds inline contents, so a method whose `PipeDocGen` steps fill a template, an `.html` file for a PDF or the `.xlsx`, `.docx` or `.pptx` file itself, lists it beside its `.mthds` files where the step's `template_file` leads: `[{ path: "invoice.mthds" }, { path: "templates/invoice.xlsx" }]`. A template is read as bytes and never travels through the conversation. A method needing any other file is sent as its folder.

**Secrets stay home.** Every tool that sends a method's files, from a folder or a list, refuses one that looks like it holds a key, a key file or a well-known key format, before anything is sent, naming the file and never the key. The [tool reference](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md#the-tools) has the rule and its limits.

**Path trust boundary.** `{ path }` values resolve relative to the server's working directory. The `{ path }` items of `files` are contracted to a fixed list of extensions, `.mthds` and the template suffixes `.html`, `.xlsx`, `.docx` and `.pptx`, so any other extension is rejected **before any filesystem access** (a prompt-injected `.env` or key-file path is never opened), and the resolved target (symlinks followed) must live inside the working-directory subtree. A wrong extension and an escape come back as `client.argument_invalid` problems located at the item (`files[i].path`), and a missing file, a non-regular file and one that cannot be read as `client.file_unreadable` problems naming the path.

## Local workshop: start it

The workshop is published on npm as [`@pipelex/mcp`](https://www.npmjs.com/package/@pipelex/mcp). You do not install it: a host spawns it on demand in your project with the command below, and on Claude Code and Codex the [Pipelex plugin](https://github.com/Pipelex/pipelex-plugins) does that for you. The `@latest` makes `npx` start the newest release rather than a copy it cached earlier. Run by hand, it prints nothing and waits for a host on its standard input.

```bash
npx -y @pipelex/mcp@latest
```

It needs Node.js 24.14.1 or later, and a `plx_sk_` Pipelex API key, since every tool calls the hosted Pipelex API. Log in once in a terminal with `npx -y @pipelex/mcp@latest login`: it signs you in at [app.pipelex.com](https://app.pipelex.com) in your browser, checks the key the app creates and saves it in `~/.pipelex/.env`, which the workshop reads whenever its host passes no `PIPELEX_API_KEY`, from its next tool call; add `--label <name>` and each login under that label replaces your key of that label instead of adding one. On a machine whose browser cannot reach the command, such as over SSH, `npx -y @pipelex/mcp@latest login --paste` takes a key you paste instead. Or create a key on the Developer page of [app.pipelex.com](https://app.pipelex.com) and set it as `PIPELEX_API_KEY` in the host's configuration, which wins over the saved one. The directory the host starts it in is the boundary for everything it reads and writes on disk. [Registering the workshop in a host](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/hosts.md) gives the login's details, the configuration for each host, every environment variable the workshop reads, and the rules of that boundary.

## Chat hosts use the Pipelex connector

ChatGPT, claude.ai and Claude Desktop do not run this server. They add the Pipelex connector, the hosted Pipelex MCP, by its address:

```
https://mcp.pipelex.com/mcp
```

There is nothing to install and no key to paste: the host walks you through signing in with your Pipelex account, and your signed-in session authorizes every call the connector makes. If you have no Pipelex account yet, create one at [app.pipelex.com](https://app.pipelex.com) before you add the connector, since signing up there also sets up the organization every call works in. The connector is a separate product with its own tools, and this repository does not hold it.

On a coding agent, prefer the workshop, which the Pipelex plugin brings — see [Which server, for which host](#which-server-for-which-host).

## You don't need both

A chat host takes the connector, and a coding agent takes the workshop through the Pipelex plugin; no host needs both. The two share no tool name, so a host that has both can tell them apart, and the workshop's instructions tell the model to use its `mthds_*` tools for all method work whenever the connector's `pipelex_*` tools are also present, and never to mix the two. The connector runs on your sign-in and the workshop on an API key, and the two can select different organizations: a method saved from the workshop is visible from the connector only when both select the same one.

The way to end up with both without choosing it: **the connector added in claude.ai syncs into Claude Code automatically.** A user signed into claude.ai with the connector enabled gets its tools in coding sessions beside the workshop's. That is harmless, but it doubles the tool list for no added capability, so you can turn the connector off for those sessions:

- In Claude Code, `/mcp` is the entry point. A connector you haven't signed into is collapsed behind a **"Show unused connectors"** row (Claude Code v2.1.161+) — expand it to find Pipelex.
- For one project, list it under `deniedMcpServers` in `.claude/settings.json`.

Avoid `disableClaudeAiConnectors: true` for this. It turns off the Pipelex connector, but also every other connector on your Claude account, such as Gmail, Google Drive and Calendar, and those are what an agent uses to fetch a method's inputs from your mail or files and to deliver its results.

## Documentation

- [Tools reference](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/tools.md): every tool's input, structured result and behavior.
- [Registering the workshop in a host](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/hosts.md): the configuration for Claude Code, Codex, Cursor, Claude Desktop and Mistral Vibe, the environment variables the workshop reads, and the working directory it is bound to.
- [Developing pipelex-mcp](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/development.md): the layout, the build, the test suites and versioning.
- [Architecture](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/architecture.md) and [Testing](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/testing.md): how the workshop and its capability core are built, module by module, and how they are tested, the live drift detectors included.
- [Client identification](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/client-identification.md): the `User-Agent` every request to the Pipelex API carries, naming this server and the host behind it.
- [The specification](https://github.com/Pipelex/pipelex-mcp/blob/main/SPEC.md): the source of truth for the full tool contracts and the verdict discipline.
- [The changelog](https://github.com/Pipelex/pipelex-mcp/blob/main/CHANGELOG.md): what each release changed, under the version npm publishes it as.
- [The Pipelex documentation](https://docs.pipelex.com/) and [the MTHDS standard](https://mthds.ai/).

## Develop

The repository is one package at its root, `@pipelex/mcp`, whose sources are under `src/`: the server and, under `src/capabilities/`, the capability core it is built on. To work on it, clone it, then, from the root:

```bash
make install   # install the dependencies
make check     # lint, formatting, the text budgets, the build and typecheck
make test      # the hermetic test suite, which never touches the network
```

A coding agent runs `make agent-test` instead of `make test`: the same suite, with its output shown only when a test fails. `make dev-local` runs the workshop from source. [Developing pipelex-mcp](https://github.com/Pipelex/pipelex-mcp/blob/main/docs/development.md) covers the layout, the live test suites against the Pipelex API, and how the workshop is versioned and released.

## License

`@pipelex/mcp` is licensed under the Elastic License 2.0 (ELv2), a source-available license. You may run it for your own team or company, on your own infrastructure or in your own cloud account. What the Elastic License 2.0 rules out is offering others a remote MCP server through which they run the methods of their choice, their own or a catalog's. See [LICENSE](https://github.com/Pipelex/pipelex-mcp/blob/main/LICENSE) for the full terms, including notices and redistribution, and the [license page](https://docs.pipelex.com/latest/license/) for how Pipelex reads them.