You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Unix-style pipelines for MCP tools — compose complex tool workflows as single pipeline requests**
6
7
7
-
MCP Shell is an MCP server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side.
8
+
## Introduction
8
9
9
-
```bash
10
-
# What agents can express:
11
-
fetch https://api.example.com/users \
12
-
| jq -c '.[] | .profile_url' \
13
-
| for_each fetch \
14
-
| jq '[.[] | select(.active)] | sort_by(.name)'
15
-
```
10
+
Model Context Shell is a system that lets AI agents compose [MCP](https://modelcontextprotocol.io/) tool calls similar to Unix shell scripting. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side.
16
11
17
-
This single pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context.
12
+
For example, an agent can express a multi-step workflow as a single pipeline:
MCP is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, agents hit real limits:
19
+
This pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context.
20
+
21
+
### Why this matters
22
+
23
+
[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, the agent has to orchestrate each tool call individually, loading all intermediate results into context. Model Context Shell adds a pipeline layer — the agent sends a single pipeline, and the server coordinates the tools, returning only the final result:
24
+
25
+
```mermaid
26
+
flowchart LR
27
+
subgraph without["Standard Workflow"]
28
+
direction TB
29
+
A1[Agent]
30
+
A1 <--> T1a[Tool A]
31
+
A1 <--> T2a[Tool B]
32
+
A1 <--> T3a[Tool C]
33
+
end
34
+
subgraph with["Model Context Shell"]
35
+
direction TB
36
+
A2[Agent] <--> S[Shell]
37
+
S --> T1b[Tool A] --> S
38
+
S --> T2b[Tool B] --> S
39
+
S --> T3b[Tool C] --> S
40
+
end
41
+
without ~~~ with
42
+
```
22
43
23
-
|| Without MCP Shell | With MCP Shell|
44
+
|| Without | With |
24
45
|---|---|---|
25
46
|**Orchestration**| Agent coordinates every tool call, loading intermediate results into context | Single pipeline request, only final result returned |
26
-
|**Composition**| Tools combined through LLM reasoning| Native Unix-style piping between tools |
47
+
|**Composition**| Tools combined by the agent one call at a time| Native Unix-style piping between tools |
27
48
|**Data scale**| Limited by context window | Streaming/iterator model handles datasets larger than memory |
28
49
|**Reliability**| LLM-dependent control flow | Deterministic shell pipeline execution |
29
50
|**Permissions**| Complex tasks push toward full shell access | Sandboxed execution with allowed commands only |
30
51
31
-
## Real-World Example
52
+
###Real-world example
32
53
33
54
Example query: "List all Pokemon over 50 kg that have the chlorophyll ability"
34
55
@@ -38,15 +59,68 @@ Instead of 7+ separate tool calls loading all Pokemon data into context, the age
38
59
- Fetched each Pokemon's details (7 API calls)
39
60
- Filtered by weight and formatted the results
40
61
41
-
**Result**: 50%+ reduction in tokens and only the final answer loaded into context.
62
+
**Result**: Only the final answer is loaded into context — no intermediate API responses.
63
+
64
+
In practice, agents don't construct the perfect pipeline on the first try. They typically run a few exploratory queries first to understand the shape of the data before building the final pipeline. To keep this process fast and cheap, the server includes a preview stage powered by [headson](https://github.com/kantord/headson) that returns a compact structural summary of the data — enough for the agent to plan its transformations without loading the full dataset into context.
65
+
66
+
### Design
67
+
68
+
Agents already have access to full shell environments and can call any CLI tool, which has significant overlap with what MCP tools provide. Rather than duplicating that, Model Context Shell explores whether similar workflows can be achieved in a safer, simpler MCP-native environment. Patterns like parallel map-reduce over tool call results are not common today because MCP doesn't natively support them, but they seem like a natural fit for coordinating tool calls — imagine fetching all console errors via a Chrome DevTools MCP server and creating a separate GitHub issue for each one. A system tailored to these patterns can make them first-class operations.
69
+
70
+
The execution engine works with JSON pipeline definitions directly — agents construct pipelines from the MCP tool schema alone, without needing shell syntax. Commands are never passed through a shell interpreter; each command and its arguments are passed as separate elements to the underlying process (`shell=False`), eliminating shell injection risks entirely. Data flows between stages as JSON, preserving types through the pipeline rather than reducing everything to strings. MCP tool arguments are validated against their JSON Schema by the receiving server, giving agents type-checked feedback when they construct pipelines incorrectly.
71
+
72
+
The result is a more constrained system compared to a general-purpose shell — only a fixed set of data transformation commands is available, and all execution happens inside a container.
73
+
74
+
### How it works
75
+
76
+
Model Context Shell is packaged as an MCP server, which makes it easy to use with any agent that supports the protocol. It could also be packaged as a library built directly into an agent.
77
+
78
+
The server exposes four tools to the agent via MCP:
79
+
80
+
| Tool | Purpose |
81
+
|---|---|
82
+
|`execute_pipeline`| Execute a pipeline of tool calls and shell commands |
83
+
|`list_all_tools`| Discover all tools available from MCP servers via [ToolHive](https://stacklok.com/download/)|
84
+
|`get_tool_details`| Get the full schema and description for a specific tool |
85
+
|`list_available_shell_commands`| Show the whitelist of allowed CLI commands |
86
+
87
+
The agent constructs pipelines as JSON arrays of stages. Data flows from one stage to the next, similar to Unix pipes. There are three stage types:
88
+
89
+
**Tool stages** call external MCP tools discovered through ToolHive:
**Preview stages** show a summarized view of the data at any point in the pipeline, useful for the agent to understand the data structure before writing transformations:
100
+
```json
101
+
{"type": "preview", "chars": 3000}
102
+
```
42
103
43
-
## Installation
104
+
Any tool stage can set `"for_each": true` to process items one-by-one. The preceding stage must output JSONL (one JSON object per line), and the tool is called once per line. Results are collected into an array. This enables patterns like "fetch a list of URLs, then fetch each one" in a single pipeline call, using a single reused connection for efficiency.
105
+
106
+
Here is a full example — a pipeline that fetches users, extracts their profile URLs, fetches each profile, and filters for active users:
-[ToolHive](https://toolhive.ai) (`thv`) for running and managing MCP servers
121
+
-[ToolHive](https://stacklok.com/download/) (`thv`) — a runtime for managing MCP servers
48
122
49
-
### Quick Start
123
+
### Quick start
50
124
51
125
Run the pre-built image from GitHub Container Registry:
52
126
@@ -58,36 +132,52 @@ thv run ghcr.io/stackloklabs/model-context-shell:latest --network host --foregro
58
132
thv run ghcr.io/stackloklabs/model-context-shell:latest --foreground --transport streamable-http
59
133
```
60
134
61
-
Once running, MCP Shell is available to any AI agent that ToolHive supports — no additional integration required.
135
+
Once running, Model Context Shell is available to any AI agent that ToolHive supports — no additional integration required. It works with any existing MCP servers running through ToolHive, and relies on ToolHive's authentication model for connected servers.
136
+
137
+
### Tips
138
+
139
+
**Connect only Model Context Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside Model Context Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. The server can access all your MCP servers through ToolHive automatically.
140
+
141
+
**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use Model Context Shell pipelines to combine multiple tool calls efficiently").
62
142
63
143
## Security
64
144
65
-
MCP Shell runs in a containerized environment through ToolHive, so commands have no direct access to the user's filesystem — only through explicitly configured MCP servers.
145
+
ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network. The MCP servers it coordinates also run in their own separate containers, managed by ToolHive.
146
+
147
+
-**Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`)
148
+
-**No shell injection**: Commands are executed with `shell=False`, arguments passed separately
149
+
-**MCP tools only**: All external operations go through approved MCP servers
66
150
67
-
-**Containerized**: Runs isolated from the host system
68
-
-**Allowed Commands**: Only safe, read-only data transformation commands are permitted
69
-
-**No Shell Injection**: Commands are executed with `shell=False`, args passed separately
70
-
-**MCP Tools Only**: All external operations go through approved MCP servers
151
+
## Development
71
152
72
-
##Usage Tips
153
+
### Requirements
73
154
74
-
**Connect only MCP Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside MCP Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. MCP Shell can access all your MCP servers through ToolHive automatically.
155
+
- Python 3.13+
156
+
-[uv](https://docs.astral.sh/uv/) for dependency management
75
157
76
-
**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use MCP Shell pipelines to combine multiple tool calls efficiently").
158
+
### Setup
77
159
78
-
## FAQ
160
+
```bash
161
+
uv sync --group dev
162
+
```
79
163
80
-
**Q: Does this work with my existing MCP servers?**
164
+
### Running tests
81
165
82
-
A: Yes! MCP Shell coordinates any standard MCP servers running through ToolHive.
166
+
```bash
167
+
uv run pytest
168
+
```
83
169
84
-
**Q: What about authentication?**
170
+
### Linting and type checking
85
171
86
-
A: Currently relies on ToolHive's authentication model for connected MCP servers.
172
+
```bash
173
+
uv run ruff check .
174
+
uv run ruff format --check .
175
+
uv run pyright
176
+
```
87
177
88
178
## Contributing
89
179
90
-
This is an experimental project. Contributions, ideas, and feedback are welcome!
180
+
Contributions, ideas, and feedback are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including our DCO sign-off requirement.
0 commit comments