The pi-code-mode-mcp server exposes a single exec tool that lets you write JavaScript to discover, inspect, compose, and invoke upstream MCP tools — all in one call.
Execute arbitrary JavaScript – send a raw async function body using await, loops, conditionals, Promise.all, and any Node.js built-in or network API.
Discover upstream tools – use search('keyword') for ranked results, ALL_TOOLS for a full inventory, or ALL_SERVERS to check upstream connection health.
Inspect tool schemas – call describe('mcp__server__tool') to retrieve full JSON input/output schemas before invoking.
Invoke upstream tools – call tools.mcp__<server>__<tool>(args) or call(name, args) for dynamic dispatch across multiple servers.
Compose workflows – orchestrate sequential, parallel, or conditional multi-step pipelines in a single exec call.
Return rich output – return a full CallToolResult (text, images, audio, structured content, errors) or use text(), image(), and emit() helpers for specific blocks.
Manage session state – use store(key, value), load(key), and clearStore(key?) for JSON-only in-memory state scoped to a session_id.
Full Node.js authority – access process, require(), import(), fetch(), filesystem, network, environment variables, and child-process APIs (no security sandbox).
Control execution limits – use timeout_ms to cap execution time and max_output_chars to bound returned text size.
Multiple transports & auth – connect to upstream MCP servers via stdio, Streamable HTTP, or SSE, with bearer token or OAuth support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pi-code-mode-mcp search for urgent GitHub issues and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Use JavaScript to discover and compose MCP tools through one agent-agnostic stdio server.
Code Mode exposes one model-facing tool, exec. A program can search configured MCP servers, inspect exact schemas, call tools and reduce intermediate results. Upstream schemas stay out of the model's initial context.
Use Code Mode for stages that involve:
large tool catalogs
repeated calls followed by filtering or aggregation
long deterministic chains
large intermediate results that the model does not need to inspect
Keep direct tools available for short tasks, semantic decisions, approvals, errors and rich results. A workflow can switch between direct tools and Code Mode at each stage.
The direct tools and Code Mode benchmark explains this recommendation.
Related MCP server: pi-codemode-mcp
MCP client
└─ exec({ code })
└─ code-mode-mcp
├─ search and describe upstream tools
├─ call tools from JavaScript
└─ return selected resultsCode Mode supports:
stdio, Streamable HTTP and legacy SSE upstream servers
bearer authentication and OAuth
cancellation, progress, elicitation, sampling, roots and logging
text, image, audio, resource and structured results
explicit JSON-only session state held in memory
Code Mode does not store tool results, screenshots, console output or intermediate values automatically.
You need:
Node.js 22 or newer
an MCP client that can launch a stdio server
Install version 0.4.0 from npm:
npm install --global @tmustier/code-mode-mcp@0.4.0
code-mode-mcp --helpCreate ~/.config/code-mode-mcp/mcp.json:
{
"mcpServers": {
"local": {
"command": "node",
"args": ["/absolute/path/to/server.js"]
},
"remote": {
"url": "https://example.com/mcp",
"auth": "bearer",
"bearerTokenEnv": "EXAMPLE_MCP_TOKEN"
}
}
}Check the file without starting MCP:
code-mode-mcp --check-config \
--config ~/.config/code-mode-mcp/mcp.jsonThe check excludes commands, arguments, headers, tokens and environment values from its summary.
See configuration for transports, environment expansion, OAuth and config lookup.
Add the outer Code Mode server to your client's MCP configuration:
{
"mcpServers": {
"code-mode": {
"command": "npx",
"args": [
"-y",
"@tmustier/code-mode-mcp@0.4.0",
"--config",
"/Users/you/.config/code-mode-mcp/mcp.json"
]
}
}
}Keep the upstream config separate. Do not configure Code Mode as its own upstream server.
exec toolThe code field contains a JavaScript async function body:
{
"code": "return search('app screenshot accessibility', { limit: 5 });",
"session_id": "optional-session",
"timeout_ms": 120000,
"max_output_chars": 51200
}The execution context provides:
search() for ranked tool discovery
describe() for exact schemas
tools.<name>(args) and call(name, args) for tool calls
ALL_TOOLS and ALL_SERVERS for bounded custom discovery
text(), image() and emit() for output selection
store(), load() and clearStore() for in-memory JSON state
signal for cancellation
For example:
const apps = await tools.mcp__computer_use__list_apps({});
const selected = ["Calculator", "TextEdit"];
const states = await Promise.all(
selected.map(app => tools.mcp__computer_use__get_app_state({ app }))
);
return states.map((state, index) => ({
app: selected[index],
text: state.content.find(block => block.type === "text")?.text.slice(0, 500)
}));Code Mode preserves a complete MCP CallToolResult when you return it. Filter or aggregate large results inside the program to keep model context small.
See the exec API for discovery, canonical tool names, output limits and session state.
Code passed to exec has the same authority as the Node.js process. It can access the filesystem, network, environment, processes and child processes.
node:vm controls execution and interrupts synchronous loops. It is not a security sandbox. Run Code Mode inside the operating system, container, account and credential boundary you want the agent to have.
See the security model before using Code Mode with sensitive systems.
npm ci
npm run check
npm test
npm run prepublishOnly
npm pack --dry-runRun JavaScript to discover and compose upstream MCP tools in one call.
The code is an async function body: use top-level await and return a final value. Global APIs:
search(query, options?): recall-oriented ranked discovery over tool names, descriptions, servers, titles, and top-level input property names. Options: { server?, limit? }. Use search and describe when tool names or schemas are unknown; call known names directly.
describe(name): full metadata and JSON input/output schemas for one normalized or unambiguous raw tool name.
ALL_TOOLS: frozen complete { name, server, tool, title?, description } inventory for deterministic recovery when ranked search is insufficient.
ALL_SERVERS: frozen { server, status, toolCount, error? } summaries. Check tool counts before enumerating a server.
tools.(args) or call(name, args): invoke a tool. Names are normalized as mcp____ and returned by search or ALL_TOOLS.
text(value), image(dataUrlOrMcpImage, detail?), emit(contentBlock): select MCP output blocks.
store(key, value), load(key), clearStore(key?): explicit JSON-only in-memory session state.
signal: AbortSignal for this execution.
When vocabulary is uncertain, run several short search phrasings in one script and union the results. If search misses, filter ALL_TOOLS by name/description and slice the result; do not return the whole inventory or conclude a capability is absent from one empty search. You can return a few search results mapped through describe() to inspect their schemas in one discovery call.
Nested calls can be looped, branched, or run with Promise.all. Return a complete MCP CallToolResult to preserve all its text, image, audio, resource, structured content, error, and metadata fields. Otherwise returned values become text/JSON; use image() or emit() to select rich blocks.
This is ordinary host-authority Node JavaScript, not a security sandbox. process, require(), dynamic import(), fetch(), filesystem, network, environment, and child-process APIs have the same authority as this MCP server. node:vm supplies execution context and synchronous timeout control only. Standard output is reserved for MCP; console output is captured and returned.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Raw JavaScript function body. Use top-level await and return the final value. Do not wrap it in JSON or markdown fences. | |
| session_id | No | Optional in-memory store namespace. Defaults to default. | default |
| timeout_ms | No | Optional execution timeout. Defaults to the server setting. | |
| max_output_chars | No | Optional returned-text limit. Filter large results in code instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond the annotations, such as 'ordinary host-authority Node JavaScript, not a security sandbox', detailing available APIs like process, require, fetch, and noting that console output is captured. This adds significant context not present in annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary at the top, followed by detailed sections on APIs, usage patterns, and security. It is verbose but efficiently organized, front-loading the main purpose. Minor room for trimming, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully explains return behavior: 'Return a complete MCP CallToolResult... Otherwise returned values become text/JSON; use image() or emit() to select rich blocks.' It covers error handling and use of global APIs, providing complete context for this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds minor extra value (e.g., 'Do not wrap it in JSON or markdown fences' for code), but mostly repeats schema information. No significant new parameter semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run JavaScript to discover and compose upstream MCP tools in one call.' It specifies the verb 'run' and resource 'JavaScript over MCP tools', and while no sibling tools are listed, the description uniquely defines its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool, such as 'when vocabulary is uncertain' and recommends alternatives like 'use search and describe when tool names or schemas are unknown'. It also advises against returning the whole inventory, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0execScored across 1 tool
Only one tool exists, so there is no possibility of confusion or overlap between tools. The agent can only use 'exec', making disambiguation trivial.
With only one tool named 'exec', naming is perfectly consistent. The tool name is a straightforward verb, aligning with common conventions for action-oriented tools.
The single tool 'exec' serves as a meta-orchestrator that can run arbitrary JavaScript to discover and compose other MCP tools. While unconventional, this design is intentional and scoped to its purpose. The count is minimal but arguably appropriate for a tool that replaces many specific ones.
The 'exec' tool provides a comprehensive environment to search, describe, and invoke any MCP tool, making it complete for its intended role as a discovery and composition layer. However, it lacks dedicated tools for specific operations, relying on programming logic, which may be considered a gap for agents that cannot write code.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Find and call the right MCP server for any task - pay per use, no install.
