| name | mcp-code-execution |
| description | Scaffold the code execution pattern for MCP-based agents. Use when agents call many MCP tools, intermediate data exceeds context, you need loops, or PII must stay out of context. |
| user-invocable | false |
| allowed-tools | Bash, Read, Write, Edit, Grep, Glob, TodoWrite |
| created | "2026-02-08T00:00:00.000Z" |
| modified | "2026-07-28T00:00:00.000Z" |
| reviewed | "2026-06-14T00:00:00.000Z" |
MCP Code Execution Pattern
Expert knowledge for designing agent systems that generate and execute code to interact with MCP servers, instead of calling tools directly.
For the typed-wrapper code, the six key-pattern examples, and the project
scaffolding steps, see REFERENCE.md.
When to Use This Skill
| Use code execution when... | Use direct tool calls / mcp-management when... |
|---|
| Designing agents that fan out across 10+ MCP servers or 50+ tools | Installing or configuring one or two servers in .mcp.json |
| Intermediate results are large (>10K tokens) and would blow context | Results are small and all needed by the model |
| Workflows need loops, retries, or conditionals across tool calls | Linear sequences of 2–3 tool calls |
| PII must not reach the model context | Tool responses contain no sensitive data |
| Tasks benefit from state persistence across runs | Stateless, one-shot operations |
| You want agents to accumulate reusable skills | Fixed, predefined workflows |
Core Architecture
How It Works
Instead of loading all MCP tool definitions into context upfront, the agent:
- Discovers available tools by navigating a typed file tree
- Generates TypeScript/Python code that imports and calls typed wrapper functions
- Executes the code in a sandboxed environment
- Returns only filtered/summarized results to the model
This reduces token usage from O(all_tool_definitions) to O(only_relevant_imports).
File Tree Structure
project/
├── servers/
│ ├── google-drive/
│ │ ├── getDocument.ts
│ │ ├── getSheet.ts
│ │ └── index.ts # Re-exports all tools
│ ├── salesforce/
│ │ └── index.ts
│ └── slack/
│ └── index.ts
├── skills/ # Agent-accumulated reusable functions
├── workspace/ # Persistent state between executions
├── client.ts # MCP client that routes calls to servers
└── sandbox.config.ts # Execution environment configuration
Each MCP tool gets a typed wrapper function the agent imports
(callMCPTool<T>("server__tool", input)); the agent writes ordinary code
against those wrappers. See
REFERENCE.md → Typed wrapper pattern.
Key Patterns
Six patterns make this efficient — each with a worked code example in
REFERENCE.md → Key patterns:
| Pattern | What it buys |
|---|
| Progressive tool discovery | Navigate servers/ on demand — ~150K tokens → ~2K (98.7% reduction) |
| Context-efficient filtering | Filter large datasets in the sandbox; only a summary reaches the model |
| Native control flow | Loops/retries/conditionals run in the sandbox, not as chained tool calls |
| PII tokenization | The client tokenizes sensitive fields so PII never enters model context |
| State persistence | Save intermediate results to workspace/ for cross-execution continuity |
| Skill accumulation | Persist reusable functions to skills/ for future executions |
Scaffolding a New Project
The five-step scaffold — identify servers → generate typed wrappers → create the
routing client → configure the sandbox → wire the agent loop — is detailed with
code in REFERENCE.md → Scaffolding a new project.
The agent loop becomes: explore servers/ → generate code → execute in sandbox
→ filtered output returns → decide done or iterate.
Security Checklist
| Item | Status |
|---|
| Sandboxed execution environment | Required |
| Resource limits (CPU, memory, disk) | Required |
| Network isolation (MCP servers only) | Required |
| Execution timeout | Required |
| PII tokenization in MCP client | Recommended for sensitive data |
| Audit logging of all executions | Recommended |
Read-only access to servers/ | Recommended |
Scoped write access to workspace/ only | Recommended |
Quick Reference
Token Impact
| Approach | Tool definitions | Intermediate data | Total |
|---|
| Direct tool calls | All loaded upfront | Passes through context | High |
| Code execution | On-demand discovery | Stays in sandbox | Low |
When NOT to Use This Pattern
- Simple integrations with 1–3 MCP servers
- All tool responses are small and needed by the model
- No sensitive data in tool responses
- Infrastructure complexity isn't justified (sandbox setup, monitoring)
- Prototype or proof-of-concept stage
Reference
