Code Mode

​

Overview

The Problem: When you connect 8-10 MCP servers (150+ tools), every single request includes all tool definitions in the context. The LLM spends most of its budget reading tool catalogs instead of doing actual work.

​

The Impact

• 6 LLM turns
• 100 tools in context every turn (600 tool-definition tokens)
• All intermediate results flow through the model

• 3-4 LLM turns
• Only 3 tools + definitions on-demand
• Intermediate results processed in sandbox

1. listToolFiles - Discover available MCP servers
2. readToolFile - Load TypeScript definitions on-demand
3. executeToolCode - Execute TypeScript code with full tool bindings

​

When to Use Code Mode

• ✅ 3+ MCP servers connected
• ✅ Complex multi-step workflows
• ✅ Concerned about token costs or latency
• ✅ Tools that need to interact with each other

• ✅ Only 1-2 small MCP servers
• ✅ Simple, direct tool calls
• ✅ Very latency-sensitive use cases (though Code Mode is usually faster)

​

How Code Mode Works

​

The Three Tools

​

The Execution Flow

​

Why This Matters at Scale

​

Classic MCP with 5 servers (100 tools):

Turn 1: Prompt + search query + [100 tool definitions]
Turn 2: Prompt + search result + [100 tool definitions]
Turn 3: Prompt + channel list + [100 tool definitions]
Turn 4: Prompt + video list + [100 tool definitions]
Turn 5: Prompt + summaries + [100 tool definitions]
Turn 6: Prompt + doc result + [100 tool definitions]

Total: 6 LLM calls, ~600+ tokens in tool definitions alone

​

Code Mode with same 5 servers:

Turn 1: Prompt + 3 tools (listToolFiles, readToolFile, executeToolCode)
Turn 2: Prompt + server list + 3 tools
Turn 3: Prompt + selected definitions + 3 tools + [EXECUTES CODE]
        [YouTube search, channel list, videos, summaries, doc creation all happen in sandbox]
Turn 4: Prompt + final result + 3 tools

Total: 3-4 LLM calls, ~50 tokens in tool definitions
Result: 50% cost reduction, 3-4x fewer LLM round trips

​

Enabling Code Mode

• Web UI
• API
• config.json

​

Enable Code Mode for a Client

1. Navigate to MCP Gateway in the sidebar
2. Click on a client row to open the configuration sheet

3. In the Basic Information section, toggle Code Mode Client to enabled
4. Click Save Changes

Once enabled:

• This client’s tools are no longer in the default tool list
• They become accessible through listToolFiles() and readToolFile()
• The AI can write code using executeToolCode() to call them

Copy

Ask AI

# When adding a new client
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "youtube",
    "connection_type": "http",
    "connection_string": "http://localhost:3001/mcp",
    "tools_to_execute": ["*"],
    "is_code_mode_client": true
  }'

# Or update an existing client
curl -X PUT http://localhost:8080/api/mcp/client/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "youtube",
    "connection_type": "http",
    "connection_string": "http://localhost:3001/mcp",
    "tools_to_execute": ["*"],
    "is_code_mode_client": true
  }'

Copy

Ask AI

{
  "mcp": {
    "client_configs": [
      {
        "name": "youtube",
        "connection_type": "http",
        "connection_string": "http://localhost:3001/mcp",
        "tools_to_execute": ["*"],
        "is_code_mode_client": true
      },
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-filesystem"]
        },
        "tools_to_execute": ["*"],
        "is_code_mode_client": true
      }
    ]
  }
}

​

Go SDK Setup

mcpConfig := &schemas.MCPConfig{
    ClientConfigs: []schemas.MCPClientConfig{
        {
            Name:             "youtube",
            ConnectionType:   schemas.MCPConnectionTypeHTTP,
            ConnectionString: bifrost.Ptr("http://localhost:3001/mcp"),
            ToolsToExecute:   []string{"*"},
            IsCodeModeClient: true, // Enable code mode
        },
        {
            Name:           "filesystem",
            ConnectionType: schemas.MCPConnectionTypeSTDIO,
            StdioConfig: &schemas.MCPStdioConfig{
                Command: "npx",
                Args:    []string{"-y", "@anthropic/mcp-filesystem"},
            },
            ToolsToExecute:   []string{"*"},
            IsCodeModeClient: true, // Enable code mode
        },
    },
}

​

The Three Code Mode Tools

​

1. listToolFiles

servers/
  youtube.d.ts
  filesystem.d.ts

servers/
  youtube/
    search.d.ts
    get_video.d.ts
  filesystem/
    read_file.d.ts
    write_file.d.ts

​

2. readToolFile

• fileName (required): Path like servers/youtube.d.ts or servers/youtube/search.d.ts
• startLine (optional): 1-based starting line for partial reads
• endLine (optional): 1-based ending line for partial reads

// Type definitions for youtube MCP server
// Usage: const result = await youtube.search({ query: "..." });

interface SearchInput {
  query: string;  // Search query (required)
  maxResults?: number;  // Max results to return (optional)
}

interface SearchResponse {
  [key: string]: any;
}

export async function search(input: SearchInput): Promise<SearchResponse>;

​

3. executeToolCode

• code (required): TypeScript code to execute

• TypeScript is transpiled to ES5-compatible JavaScript
• All code mode servers are exposed as global objects (e.g., youtube, filesystem)
• Each server has async functions for its tools (e.g., youtube.search())
• Console output (log, error, warn, info) is captured
• Use return to return a value from the code
• Tool execution timeout applies (default 30s)

// Search YouTube and return formatted results
const results = await youtube.search({ query: "AI news", maxResults: 5 });
const titles = results.items.map(item => item.snippet.title);
console.log("Found", titles.length, "videos");
return { titles, count: titles.length };

​

Binding Levels

​

Server-Level Binding (Default)

servers/
  youtube.d.ts        ← Contains all youtube tools
  filesystem.d.ts     ← Contains all filesystem tools

• Servers with few tools
• When you want to see all tools at once
• Simpler discovery workflow

​

Tool-Level Binding

servers/
  youtube/
    search.d.ts
    get_video.d.ts
    get_channel.d.ts
  filesystem/
    read_file.d.ts
    write_file.d.ts
    list_directory.d.ts

• Servers with many tools
• When tools have large/complex schemas
• More focused documentation per tool

​

Configuring Binding Level

• Web UI
• config.json
• Go SDK

Binding level can be viewed in the MCP configuration overview:

• Server-level (default): One .d.ts file per MCP server
  • Use when: 5-20 tools per server, want simple discovery
  • Example: servers/youtube.d.ts contains all YouTube tools
• Tool-level: One .d.ts file per individual tool
  • Use when: 30+ tools per server, want minimal context bloat
  • Example: servers/youtube/search.d.ts, servers/youtube/list_channels.d.ts

Both modes use the same three-tool interface (listToolFiles, readToolFile, executeToolCode). The choice is purely about context efficiency per read operation.

Copy

Ask AI

{
  "mcp": {
    "tool_manager_config": {
      "code_mode_binding_level": "server"
    }
  }
}

Options: "server" (default) or "tool"

Copy

Ask AI

mcpConfig := &schemas.MCPConfig{
    ToolManagerConfig: &schemas.MCPToolManagerConfig{
        CodeModeBindingLevel: schemas.CodeModeBindingLevelTool, // or CodeModeBindingLevelServer
    },
    ClientConfigs: []schemas.MCPClientConfig{
        // ... clients
    },
}

​

Auto-Execution with Code Mode

1. The listToolFiles and readToolFile tools are always auto-executable (they’re read-only)
2. The executeToolCode tool is auto-executable only if all tool calls within the code are allowed

​

How Validation Works

1. Bifrost parses the TypeScript code
2. Extracts all serverName.toolName() calls
3. Checks each call against tools_to_auto_execute for that server
4. If ALL calls are allowed → auto-execute
5. If ANY call is not allowed → return to user for approval

{
  "name": "youtube",
  "tools_to_execute": ["*"],
  "tools_to_auto_execute": ["search"],
  "is_code_mode_client": true
}

// This code WILL auto-execute (only uses search)
const results = await youtube.search({ query: "AI" });
return results;

// This code will NOT auto-execute (uses delete_video which is not in auto-execute list)
await youtube.delete_video({ id: "abc123" });

​

Code Execution Environment

​

Available APIs

​

Runtime Environment Details

// If you have a 'youtube' code mode client with a 'search' tool
const results = await youtube.search({ query: "AI news" });

1. Import/export statements are stripped
2. TypeScript is transpiled to JavaScript (ES5 compatible)
3. Tool calls are extracted and validated
4. Code executes in isolated VM context
5. Return value is automatically serialized to JSON

• Default timeout: 30 seconds per tool execution
• Memory isolation: Each execution gets its own context
• No access to host file system or network
• Logs captured from console methods

​

Error Handling

// Error: youtube is not defined
// Hints:
// - Variable or identifier 'youtube' is not defined
// - Available server keys: youtubeAPI, filesystem
// - Use one of the available server keys as the object name

​

Timeouts

• Default: 30 seconds per tool call
• Configure via tool_execution_timeout in tool_manager_config
• Long-running operations are interrupted with timeout error

​

Real-World Impact Comparison

​

Scenario: E-commerce Assistant with Multiple Services

• 10 MCP servers (product catalog, inventory, payments, shipping, chat, analytics, docs, images, calendar, notifications)
• Average 15 tools per server = 150 total tools
• Complex multi-step task: “Find matching products, check inventory, compare prices, get shipping estimate, create quote”

​

Classic MCP Results

​

Code Mode Results

​

Next Steps