> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Complete configuration reference for CodeCall plugin - modes, VM presets, embedding strategies, and per-tool metadata. CodeCall configuration options CodeCall configuration options This page covers all configuration options for the CodeCall plugin, from quick presets to fine-grained control. *** ## Plugin Initialization ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { CodeCallPlugin } from '@frontmcp/plugins'; CodeCallPlugin.init({ // Tool visibility mode mode: 'codecall_only' | 'codecall_opt_in' | 'metadata_driven', // VM/sandbox configuration vm: { /* ... */ }, // Embedding/search configuration embedding: { /* ... */ }, // Tool filtering includeTools: (tool) => boolean, // Direct invoke configuration directCalls: { /* ... */ }, }); ``` *** ## Tool Visibility Modes Control which tools appear in `list_tools` vs. CodeCall. ### `codecall_only` (Recommended) **Default mode.** Hides all tools from `list_tools`, exposes via CodeCall. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ mode: 'codecall_only', }); ``` | Tool Location | Behavior | | ------------- | --------------------------------------- | | `list_tools` | Only CodeCall meta-tools visible | | CodeCall | All tools searchable and callable | | Override | Set `visibleInListTools: true` per tool | **Best for:** Large toolsets (20+), OpenAPI adapters, clean client experience. ### `codecall_opt_in` Tools must explicitly opt into CodeCall. All tools visible in `list_tools` by default. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ mode: 'codecall_opt_in', }); ``` | Tool Location | Behavior | | ------------- | ----------------------------------------- | | `list_tools` | All tools visible (default MCP behavior) | | CodeCall | Only tools with `enabledInCodeCall: true` | **Best for:** Gradual migration, mixed direct/CodeCall access. ### `metadata_driven` Full control via per-tool metadata. No global assumptions. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ mode: 'metadata_driven', }); ``` | Tool Location | Behavior | | ------------- | --------------------------------------------- | | `list_tools` | Based on `visibleInListTools` (default: true) | | CodeCall | Based on `enabledInCodeCall` (default: false) | **Best for:** Small toolsets, fine-grained control. *** ## Per-Tool Metadata Control individual tool behavior with the `codecall` metadata field: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} @Tool({ name: 'users:list', description: 'List all users', codecall: { // Is this tool searchable and callable via CodeCall? enabledInCodeCall: true, // default depends on mode // Is this tool visible in standard list_tools? visibleInListTools: false, // default depends on mode // App ID for multi-app filtering (auto-detected if not set) appId: 'user-service', }, }) ``` ### Metadata by Mode | Mode | `enabledInCodeCall` default | `visibleInListTools` default | | ----------------- | --------------------------- | ---------------------------- | | `codecall_only` | `true` | `false` | | `codecall_opt_in` | `false` | `true` | | `metadata_driven` | `false` | `true` | ### Common Patterns ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} codecall: { enabledInCodeCall: true, visibleInListTools: false, } ``` Use for: Most tools in `codecall_only` mode. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} codecall: { enabledInCodeCall: true, visibleInListTools: true, } ``` Use for: Core tools that should be directly accessible AND in CodeCall. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} codecall: { enabledInCodeCall: false, visibleInListTools: true, } ``` Use for: Admin tools, destructive operations, tools requiring human review. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} codecall: { enabledInCodeCall: false, visibleInListTools: true, } ``` Applied automatically to `codecall:search`, `codecall:describe`, etc. *** ## Global Tool Filtering Filter tools globally with `includeTools`: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ mode: 'codecall_only', // Only include tools matching this filter includeTools: (tool) => { // Exclude admin tools if (tool.name.startsWith('admin:')) return false; // Exclude destructive tools if (tool.metadata?.annotations?.destructiveHint) return false; // Include everything else return true; }, }); ``` The filter receives a `ToolEntry` with: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface ToolEntry { name: string; fullName: string; metadata?: { description?: string; annotations?: { destructiveHint?: boolean; idempotentHint?: boolean; readOnlyHint?: boolean; }; codecall?: { enabledInCodeCall?: boolean; visibleInListTools?: boolean; appId?: string; }; }; owner?: { id: string }; } ``` *** ## VM Configuration Configure the JavaScript sandbox: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ vm: { // Use a preset (recommended) preset: 'secure', // Or override individual settings timeoutMs: 5000, maxIterations: 10000, allowConsole: true, // Blocked identifiers (in addition to preset) disabledBuiltins: ['eval', 'Function'], disabledGlobals: ['process', 'require'], }, }); ``` ### VM Presets | Preset | Timeout | Max Iterations | Console | Use Case | | -------------- | ------- | -------------- | ------- | ---------------------------- | | `locked_down` | 2s | 2,000 | No | Ultra-sensitive environments | | `secure` | 3.5s | 5,000 | Yes | **Production default** | | `balanced` | 5s | 10,000 | Yes | Complex workflows | | `experimental` | 10s | 20,000 | Yes | Development only | ### Preset Details ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} { preset: 'locked_down', timeoutMs: 2000, maxIterations: 2000, allowConsole: false, allowLoops: false, // Only for-of allowed disabledBuiltins: ['eval', 'Function', 'AsyncFunction'], disabledGlobals: [ 'require', 'process', 'fetch', 'setTimeout', 'setInterval', 'setImmediate', 'global', 'globalThis' ], } ``` **When to use:** Healthcare, finance, PII processing, compliance-heavy environments. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} { preset: 'secure', timeoutMs: 3500, maxIterations: 5000, allowConsole: true, allowLoops: false, // Only for-of allowed disabledBuiltins: ['eval', 'Function', 'AsyncFunction'], disabledGlobals: [ 'require', 'process', 'fetch', 'setTimeout', 'setInterval', 'setImmediate', 'global', 'globalThis' ], } ``` **When to use:** Most production deployments. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} { preset: 'balanced', timeoutMs: 5000, maxIterations: 10000, allowConsole: true, allowLoops: true, // for, for-of, while allowed disabledBuiltins: ['eval', 'Function', 'AsyncFunction'], disabledGlobals: ['require', 'process', 'fetch'], } ``` **When to use:** Complex data processing, trusted model access. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} { preset: 'experimental', timeoutMs: 10000, maxIterations: 20000, allowConsole: true, allowLoops: true, disabledBuiltins: ['eval', 'Function', 'AsyncFunction'], disabledGlobals: ['require', 'process'], } ``` **When to use:** Development, testing, trusted internal tools. ### Reference Sidecar Configuration (Pass-by-Reference) The Reference Sidecar handles large data transfer between scripts and tools. Instead of passing full data through the VM, large values are stored externally with reference IDs. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ vm: { preset: 'secure', }, sidecar: { maxTotalSize: 64 * 1024 * 1024, // 64MB total storage maxReferenceSize: 16 * 1024 * 1024, // 16MB per reference extractionThreshold: 256 * 1024, // Extract strings > 256KB maxResolvedSize: 32 * 1024 * 1024, // 32MB max when resolving maxReferenceCount: 100, // Max 100 references maxResolutionDepth: 10, // Max nesting depth allowComposites: false, // Block reference concatenation }, }); ``` #### Sidecar Presets by Security Level | Config | STRICT | SECURE | STANDARD | PERMISSIVE | | ------------------- | ------ | ------ | -------- | ---------- | | maxTotalSize | 16MB | 64MB | 256MB | 1GB | | maxReferenceSize | 4MB | 16MB | 64MB | 256MB | | extractionThreshold | 64KB | 256KB | 1MB | 4MB | | maxResolvedSize | 8MB | 32MB | 128MB | 512MB | | maxReferenceCount | 50 | 100 | 500 | 1,000 | | maxResolutionDepth | 5 | 10 | 20 | 50 | | allowComposites | No | No | Yes | Yes | #### How Pass-by-Reference Works ```mermaid theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} sequenceDiagram participant Script participant Sidecar participant Tool Tool->>Sidecar: Returns large result (500KB) Sidecar->>Sidecar: Store with ref ID Sidecar->>Script: Return __REF_abc123__ Script->>Script: Process ref ID (not data) Script->>Tool: Call with __REF_abc123__ Sidecar->>Tool: Resolve ref → actual data ``` **Benefits:** * Scripts don't need to handle large data in memory * VM stays lightweight and secure * Tool results can exceed VM memory limits * Reference IDs are opaque strings (no data leakage) *** ## Embedding Configuration Configure how tools are indexed for search: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ embedding: { // Search strategy strategy: 'tfidf' | 'ml', // ML specific (requires VectoriaDB) modelName: 'Xenova/all-MiniLM-L6-v2', cacheDir: './.cache/transformers', }, }); ``` ### Strategy Comparison | Strategy | Speed | Relevance | Setup | Best For | | -------- | ------ | --------- | -------------- | ----------------------- | | `tfidf` | ⚡ Fast | Good | None | Most use cases, offline | | `ml` | Slower | Better | Model download | Large toolsets (100+) | ### TF-IDF Configuration ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} embedding: { strategy: 'tfidf', } ``` TF-IDF extracts searchable text from: * Tool name (tokenized: `users:list` → `users`, `list`) * Description (weighted 3x) * Key terms from description (4+ characters, no stop words) ### ML Configuration ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} embedding: { strategy: 'ml', modelName: 'Xenova/all-MiniLM-L6-v2', // Default cacheDir: './.cache/transformers', useHNSW: true, // For large toolsets (1000+) } ``` ML strategy uses [VectoriaDB](https://github.com/agentfront/vectoriadb) internally. The model (\~22MB) is downloaded on first use and cached locally. *** ## Direct Invocation Configure the `codecall:invoke` meta-tool for direct tool calls without VM overhead: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ directCalls: { // Enable/disable codecall:invoke enabled: true, // Optional: restrict to specific tools allowedTools: ['users:getById', 'billing:getInvoice'], }, }); ``` ### When to Use Direct Invoke | Use `codecall:invoke` | Use `codecall:execute` | | ------------------------------ | ------------------------ | | Single tool, no transformation | Multi-tool orchestration | | Latency-critical paths | Data filtering/joining | | Simple CRUD operations | Conditional logic | | Known tool name | Dynamic tool selection | ### Performance Comparison ``` codecall:invoke (direct) ├─ Parse input: ~0.1ms ├─ Tool lookup: ~0.1ms ├─ Tool execution: ~varies └─ Total overhead: ~0.2ms codecall:execute (VM) ├─ Pre-scan: ~0.5ms ├─ AST validation: ~1-2ms ├─ Code transformation: ~0.5ms ├─ VM execution: ~1-2ms ├─ Tool execution: ~varies └─ Total overhead: ~3-5ms ``` ### Error Response Format ```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} { "status": "error", "error": { "code": "TOOL_NOT_FOUND", "message": "Tool 'users:delete' is not in the allowed list", "tool": "users:delete", "allowedTools": ["users:getById", "billing:getInvoice"] } } ``` ### Security Considerations Direct invocation bypasses VM security validation. Only enable for tools you trust completely. * **allowedTools**: Always specify an explicit allowlist in production * **No script execution**: Direct calls cannot run arbitrary code * **Same tool access rules**: Tool Access Control (whitelist/blacklist) still applies * **Audit logging**: Direct calls are logged the same as scripted calls *** ## Complete Configuration Example ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { App } from '@frontmcp/sdk'; import { CodeCallPlugin } from '@frontmcp/plugins'; @App({ id: 'my-app', plugins: [ CodeCallPlugin.init({ // Hide all tools, expose via CodeCall mode: 'codecall_only', // Filter out admin and destructive tools includeTools: (tool) => { if (tool.name.startsWith('admin:')) return false; if (tool.metadata?.annotations?.destructiveHint) return false; return true; }, // Secure sandbox with custom timeout vm: { preset: 'secure', timeoutMs: 5000, // 5 second timeout allowConsole: true, }, // Fast TF-IDF search embedding: { strategy: 'tfidf', }, // Enable direct invocation for simple calls directCalls: { enabled: true, allowedTools: ['users:getById', 'health:ping'], }, }), ], }) export default class MyApp {} ``` *** ## Migration Guide ### From Direct Tools to CodeCall ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} plugins: [ CodeCallPlugin.init({ mode: 'metadata_driven' }), ] ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} @Tool({ codecall: { enabledInCodeCall: true, visibleInListTools: true }, }) ``` Verify tools work via both direct calls and CodeCall. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} CodeCallPlugin.init({ mode: 'codecall_only' }) ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} codecall: { enabledInCodeCall: true, visibleInListTools: false } ``` *** ## Related Security implications of configuration choices Performance tuning and monitoring Scripting language reference and best practices Complete meta-tool schemas and examples