# MCP Code Mode

> MCP orchestration via TypeScript execution. Use Code Mode for ALL external MCP tool calls; ~98% context reduction, type-safe.

- Skill: `michelkerkmeester/mcp-code-mode` (Agent Skill, multi-file: 76 files)
- Install (CLI): `npx get-skill add michelkerkmeester/mcp-code-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/mcp-code-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/mcp-code-mode

---


<!-- Keywords: code mode, call_tool_chain, call an mcp tool, use code mode, chain mcp tools, search_tools, list_tools, tool_info, utcp config, .utcp_config.json, tool not found, manual name prefix, prefixed env variable, register an mcp server, mcp-code-mode -->

# 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 walks `handover.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`](./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:

```typescript
{manual_name}.{manual_name}_{tool_name}
```

**Examples**:

✅ **Correct**:
```typescript
await myservice.myservice_sites_list({});
await clickup.clickup_create_task({...});
await figma.figma_get_file({...});
```

❌ **Wrong** (missing manual prefix):
```typescript
await myservice.sites_list({});        // Error: Tool not found
await clickup.create_task({...});    // Error: Tool not found
```

**See [references/naming-convention.md](references/naming-convention.md) for complete guide with troubleshooting.**

### Context Parameter

Many Code Mode tools require a `context` parameter (15-25 words) for analytics:

```typescript
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 in `a.b.c` format (e.g., `myservice.myservice.sites_list`). To call the tool, use underscore format: `myservice.myservice_sites_list()`. The `tool_info()` function shows the correct calling syntax.

### Basic Workflow

1. Discover tools with `search_tools()` or `list_tools()`.
2. Confirm exact callable syntax with `tool_info()`.
3. Execute `call_tool_chain()` with `{manual_name}.{manual_name}_{tool_name}` calls.
4. Return structured state from the TypeScript block.

Full multi-tool examples live in [references/workflows.md](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**
```typescript
// 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**
```typescript
// 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](references/configuration.md) and [assets/config-template.md](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_official` with `${CLICKUP_API_KEY}` needs `clickup__official_CLICKUP_API_KEY`.

**Example:**
- Config has `"name": "clickup"` and env section references `${CLICKUP_API_KEY}`
- Your `.env` file MUST use: `clickup_CLICKUP_API_KEY=pk_xxx`
- Using `CLICKUP_API_KEY=pk_xxx` will 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](assets/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](references/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_list` instead of `myservice.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](references/naming-convention.md)
- **Configuration fails to load** - Check [configuration.md](references/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](references/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_tools` before 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.json` and `.env` correct)
- ✅ 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](../../../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 through `generate-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](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](INSTALL-GUIDE.md).

