MCP Code Mode
Execute TypeScript code with direct access to 200+ MCP tools through progressive disclosure. Code Mode eliminates context overhead by loading tools on-demand, enabling complex multi-tool workflows in a single execution with state persistence and built-in error handling.
1. WHEN TO USE
Use Code Mode When
MANDATORY for ALL MCP tool calls:
- ✅ Calling ClickUp, Notion, Figma, MyService, Chrome DevTools, or any other MCP tools
- ✅ Accessing external APIs through MCP servers
- ✅ Managing tasks in project management tools
- ✅ Interacting with design tools, databases, or services
- ✅ Browser automation and web interactions
Do NOT Use Code Mode For
Use native tools instead:
- ❌ File operations (use Read, Write, Edit tools)
- ❌ Text searching (use Grep tool)
- ❌ File discovery (use Glob tool)
- ❌ Bash commands (use Bash tool)
- ❌ Continuity recovery (use
/speckit:resume, which walkshandover.md -> _memory.continuity -> spec docs)
See Section 4 for details on Native MCP vs Code Mode distinction.
Common Use Cases
| Scenario | Code Mode Approach | Benefit |
|---|---|---|
| Create ClickUp task | call_tool_chain({ code: "await clickup.clickup_create_task({...})" }) |
Type-safe, single execution |
| Multi-tool workflow | Figma → ClickUp → MyService in one execution | State persists, 5× faster |
| Browser automation | Chrome DevTools MCP for testing/screenshots | Sandboxed, reliable |
| Design-to-implementation | Fetch Figma design → Create task → Update CMS | Atomic workflow |
| External API access | Any MCP server (Notion, GitHub, etc.) | Progressive tool loading |
2. SMART ROUTING
mcp-code-mode is a standalone skill with one workflow mode, so a request that names an MCP tool, an external service, a multi-tool workflow or a browser automation need selects it.
A native file, search, shell or continuity request goes to the runtime's own tools instead, and a Code Mode call there exhausts context for nothing.
references/workflows.md is the default quick reference and loads first on every run, then the reference page the matched intent maps to loads next.
A run that matches no intent returns UNKNOWN_FALLBACK with the disambiguation checklist there rather than guessing.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Critical Naming Pattern
The #1 most common error when using Code Mode is using wrong function names. All MCP tool calls MUST follow this pattern:
{manual_name}.{manual_name}_{tool_name}
Examples:
✅ Correct:
await myservice.myservice_sites_list({});
await clickup.clickup_create_task({...});
await figma.figma_get_file({...});
❌ Wrong (missing manual prefix):
await myservice.sites_list({}); // Error: Tool not found
await clickup.create_task({...}); // Error: Tool not found
See references/naming-convention.md for complete guide with troubleshooting.
Context Parameter
Many Code Mode tools require a context parameter (15-25 words) for analytics:
await myservice.myservice_sites_list({
context: "Listing sites to identify collection structure for CMS update"
});
This helps with usage tracking and debugging.
Tool Name Translation
Note:
list_tools()returns names ina.b.cformat (e.g.,myservice.myservice.sites_list). To call the tool, use underscore format:myservice.myservice_sites_list(). Thetool_info()function shows the correct calling syntax.
Basic Workflow
- Discover tools with
search_tools()orlist_tools(). - Confirm exact callable syntax with
tool_info(). - Execute
call_tool_chain()with{manual_name}.{manual_name}_{tool_name}calls. - Return structured state from the TypeScript block.
Full multi-tool examples live in references/workflows.md.
4. PROJECT CONFIGURATION
Two MCP Configuration Systems
IMPORTANT: Code Mode only accesses tools in .utcp_config.json. Native MCP tools are NOT accessed through Code Mode.
1. Native MCP (opencode.json) - Servers the runtime registers directly (call directly, NOT through Code Mode):
- Code Mode server:
code_mode, the Code Mode tool itself - Not MCP: Spec Kit continuity (
/speckit:resume) and the skill advisor (.skilled/bin/skill-advisor.cjs) are commands you run, not tools you call - Note: Some AI environments have built-in extended thinking capabilities, which is why the former Sequential Thinking server was decommissioned rather than replaced.
2. Code Mode MCP (.utcp_config.json) - External tools accessed through Code Mode:
- MCP Config:
.utcp_config.json(project root) - Environment Variables:
.env(project root) - External tools: MyService, Figma, Chrome DevTools, ClickUp, Notion, etc.
- These are accessed via
call_tool_chain()wrapper
How to Discover Available Code Mode Tools
- These discovery methods ONLY work for Code Mode tools in
.utcp_config.json - They show only Code Mode manuals, never a natively registered MCP server
Step 1: Check Configuration
// Read .utcp_config.json to see configured Code Mode MCP servers
// Look for "manual_call_templates" array
// Each object has a "name" field (this is the manual name)
// Check "disabled" field - if true, server is not active
// NOTE: natively registered MCP servers are NOT in this file;
// they are called directly, never through Code Mode
Step 2: Use Progressive Discovery
// Search for Code Mode tools by description
const tools = await search_tools({
task_description: "browser automation",
limit: 10
});
// List all available Code Mode tools
const allTools = await list_tools();
// Get info about a specific Code Mode tool
const info = await tool_info({
tool_name: "server_name.server_name_tool_name"
});
// NOTE: These discovery tools are part of Code Mode
// They only show tools configured in .utcp_config.json
// Natively registered MCP servers will NOT appear in these results
Critical Naming Convention (Code Mode Tools Only)
See Section 3: Critical Naming Pattern for the complete guide.
Quick reminder: {manual_name}.{manual_name}_{tool_name} (e.g., myservice.myservice_sites_list())
Configuration Structure
Use .utcp_config.json with manual_call_templates[]; each entry defines the manual name, MCP server command/args/env, and disabled state. See references/configuration.md and assets/config-template.md.
Critical: Prefixed Environment Variables
⚠️ IMPORTANT: Code Mode prefixes ALL environment variables with
{manual_name}_from your configuration, doubling each underscore in the manual name first:clickup_officialwith${CLICKUP_API_KEY}needsclickup__official_CLICKUP_API_KEY.
Example:
- Config has
"name": "clickup"and env section references${CLICKUP_API_KEY} - Your
.envfile MUST use:clickup_CLICKUP_API_KEY=pk_xxx - Using
CLICKUP_API_KEY=pk_xxxwill cause:Error: Variable 'clickup_CLICKUP_API_KEY' not found
Quick Reference:
| Manual Name | Config Reference | .env Variable |
|---|---|---|
clickup |
${CLICKUP_API_KEY} |
clickup_CLICKUP_API_KEY |
figma |
${FIGMA_API_KEY} |
figma_FIGMA_API_KEY |
notion |
${NOTION_TOKEN} |
notion_NOTION_TOKEN |
See env-template.md for complete examples.
How to Check Active Code Mode Servers
IMPORTANT: This only shows Code Mode manuals in .utcp_config.json, never a natively registered server
Run list_tools() through Code Mode and group returned names by the prefix before the first dot. Natively registered servers will not appear.
5. RULES
✅ ALWAYS
- Use Code Mode for ALL MCP tool calls - Mandatory for ClickUp, Notion, Figma, MyService, Chrome DevTools, etc.
- Follow naming pattern:
{manual_name}.{manual_name}_{tool_name}(see naming-convention.md) - Use progressive discovery:
search_tools()before calling unknown tools - Use try/catch for error handling in multi-step workflows
- Set appropriate timeouts: 30s (simple), 60s (complex), 120s+ (very complex)
- Console.log progress in complex workflows for debugging
- Structure return values consistently:
{ success, data, errors, timestamp }
⛔ NEVER
- Skip Code Mode for MCP tools - Direct MCP calls cause context exhaustion
- Use wrong naming pattern -
myservice.sites_listinstead ofmyservice.myservice_sites_list - Guess tool names - Use
search_tools()to discover correct names - Ignore TypeScript errors - Type safety prevents runtime errors
- Skip error handling - Unhandled errors crash entire workflow
- Use Code Mode for file operations - Use Read/Write/Edit tools instead
- Assume tool availability - Verify with
list_tools()first
⚠️ ESCALATE IF
- Tool naming errors persist after consulting naming-convention.md
- Configuration fails to load - Check configuration.md
- Environment variables not found - Verify .env file exists and syntax is correct
- MCP server fails to start - Check command/args in .utcp_config.json
- Tools not discovered - Verify manual name matches configuration
- Execution timeout - Increase timeout or break into smaller operations
- Need to add new MCP server - Follow guide in configuration.md
6. SUCCESS CRITERIA
Code Mode implementation complete when:
- ✅ All MCP tool calls use
call_tool_chain(no direct tool calls) - ✅ Tool naming follows
{manual_name}.{manual_name}_{tool_name}pattern - ✅ Progressive discovery used (
search_toolsbefore calling) - ✅ Error handling implemented (try/catch for critical operations)
- ✅ Console logging tracks workflow progress
- ✅ Return values structured consistently
- ✅ Timeouts set appropriately for workflow complexity
- ✅ Configuration validated (
.utcp_config.jsonand.envcorrect) - ✅ Type safety verified (no TypeScript errors)
- ✅ Multi-tool workflows execute atomically (all succeed or all fail)
7. INTEGRATION POINTS
Framework Integration
This skill operates within the behavioral framework defined in AGENTS.md.
Key integrations:
- Gate 2: Skill routing via
.skilled/bin/skill-advisor.cjs - Tool Routing: Per AGENTS.md Section 5 decision tree
- Continuity: Context preserved by
/speckit:save, which writes throughgenerate-context.js
Cross-Skill Collaboration
External Tool Integration:
- Use mcp-code-mode for external tool integration (MyService, Figma, ClickUp, etc.)
- Example: Create ClickUp task → Update Notion docs → Post to external CMS
Workflow: discover tools, call them inside one call_tool_chain() execution, return state for the caller, and surface errors explicitly.
Triggers
Automatic activation when:
- User mentions MCP tool names (ClickUp, Notion, Figma, MyService, etc.)
- Request involves external tool integration
- Multi-tool workflow described
- Browser automation needed (Chrome DevTools)
Outputs
What Code Mode produces:
- External tool operation results (tasks created, data fetched, etc.)
- Workflow execution logs (console.log captured)
- Error details (if failures occur)
- State snapshots (all variables returned)
8. QUICK REFERENCE
Use search_tools(), tool_info(), list_tools(), and call_tool_chain() as the core command set. For parallel execution, use Promise.all() when all calls must succeed and Promise.allSettled() when partial success is acceptable. Full examples live in references/workflows.md.
Critical Naming Pattern
See Section 3: Critical Naming Pattern for the complete guide with examples.
Pattern: {manual_name}.{manual_name}_{tool_name}
Timeout Guidelines
- Simple (1-2 tools): 30s (default)
- Complex (3-5 tools): 60s
- Very complex (6+ tools): 120s+
9. REFERENCES AND RELATED RESOURCES
The router discovers reference and asset docs dynamically. Start with references/naming-convention.md, references/configuration.md, references/tool-catalog.md, references/workflows.md, references/architecture.md, assets/config-template.md and assets/env-template.md.
Then load task-specific resources from references/, templates from assets/, and automation from scripts/ when present.
Scripts: scripts/install.sh, scripts/update.sh, scripts/doctor.sh, scripts/validate_config.py.
Related skills: mcp-tooling, whose modes (for example mcp-chrome-devtools for browser debugging) reach their MCP servers through Code Mode.
Install guide: INSTALL-GUIDE.md.