> ## 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.

<img noZoom className="hidden dark:block blog-full-image" src="https://mintcdn.com/frontegg-7f203039/7CkIPzCpfNE4vSLj/assets/banners/codecall-plugin/code-call-options.dark.png?fit=max&auto=format&n=7CkIPzCpfNE4vSLj&q=85&s=94cdae3fc3d093b1312334bff3cfc720" alt="CodeCall configuration options" width="1536" height="1024" data-path="assets/banners/codecall-plugin/code-call-options.dark.png" />

<img noZoom className="block dark:hidden blog-full-image" src="https://mintcdn.com/frontegg-7f203039/7CkIPzCpfNE4vSLj/assets/banners/codecall-plugin/code-call-options.light.png?fit=max&auto=format&n=7CkIPzCpfNE4vSLj&q=85&s=087b266bc5b7415679f130436b2c9a05" alt="CodeCall configuration options" width="1536" height="1024" data-path="assets/banners/codecall-plugin/code-call-options.light.png" />

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/plugin-codecall';

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

<AccordionGroup>
  <Accordion title="Hide from list_tools, available in CodeCall">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    codecall: {
      enabledInCodeCall: true,
      visibleInListTools: false,
    }
    ```

    Use for: Most tools in `codecall_only` mode.
  </Accordion>

  <Accordion title="Visible everywhere">
    ```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.
  </Accordion>

  <Accordion title="Direct access only, no 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.
  </Accordion>

  <Accordion title="CodeCall meta-tools only">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    codecall: {
      enabledInCodeCall: false,
      visibleInListTools: true,
    }
    ```

    Applied automatically to `codecall:search`, `codecall:describe`, etc.
  </Accordion>
</AccordionGroup>

***

## 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 tools tagged as destructive
    if (tool.tags?.includes('destructive')) return false;

    // Include everything else
    return true;
  },
});
```

The filter receives an `IncludeToolsFilterToolInfo`:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface IncludeToolsFilterToolInfo {
  name: string;          // the tool's own name, e.g. 'admin:deleteUser' — never prefixed with the app id
  fullName?: string;     // the qualified name, e.g. 'crm:admin:deleteUser'
  appId?: string;        // the owning app's id, also for tools the app's adapters and plugins provide
  source?: string;       // codecall.source
  description?: string;
  tags?: string[];       // codecall.tags, falling back to the tool's tags
  annotations?: Readonly<{ readOnlyHint?: boolean; destructiveHint?: boolean; /* ... */ }>;
  metadata?: Readonly<Record<string, unknown>>; // the tool's declared metadata (annotations, tags, codecall, ...)
}
```

So a filter can decide from the tool's annotations, e.g. `includeTools: (tool) => !tool.annotations?.destructiveHint`
(`tool.metadata?.annotations` is the same object). `directCalls.filter` receives the same object.

`name` is the name the tool was declared with. A tool `admin:deleteUser` in app `crm` is also reachable
as `crm:admin:deleteUser`, but the filter always sees `admin:deleteUser`; use `appId` to filter by app.

The filter is an access control, not only a search setting. CodeCall runs the same decision, with the
same `tool` object, for `codecall:search`, `codecall:describe`, `callTool` and `getTool` in
`codecall:execute`, the namespace bindings a script receives, and `codecall:invoke`. A tool the filter
excludes is absent from search, reported as not found by describe, and refused at execution.

***

## 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,
    maxSteps: 10000,
    allowConsole: true,

    // Blocked identifiers (in addition to preset)
    disabledBuiltins: ['eval', 'Function'],
    disabledGlobals: ['process', 'require'],
  },
});
```

### VM Presets

| Preset | Timeout | Max Steps | 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

<Tabs>
  <Tab title="locked_down">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    {
      preset: 'locked_down',
      timeoutMs: 2000,
      maxSteps: 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.
  </Tab>

  <Tab title="secure">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    {
      preset: 'secure',
      timeoutMs: 3500,
      maxSteps: 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.
  </Tab>

  <Tab title="balanced">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    {
      preset: 'balanced',
      timeoutMs: 5000,
      maxSteps: 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.
  </Tab>

  <Tab title="experimental">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    {
      preset: 'experimental',
      timeoutMs: 10000,
      maxSteps: 20000,
      allowConsole: true,
      allowLoops: true,
      disabledBuiltins: ['eval', 'Function', 'AsyncFunction'],
      disabledGlobals: ['require', 'process'],
    }
    ```

    **When to use:** Development, testing, trusted internal tools.
  </Tab>
</Tabs>

### 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: {
    enabled: true,                       // opt-in (default: false)
    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
    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 |
| 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+)
}
```

<Note>
  ML strategy uses [VectoriaDB](https://github.com/agentfront/vectoriadb) internally. The model (\~22MB) is downloaded on first use and cached locally.
</Note>

***

## 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'],
  },
});
```

Each `allowedTools` entry matches a tool's own name (`users:getById`) or its qualified
`<appId>:<name>` (`my-app:users:getById`). List the qualified name to allow the tool from one app
only; a bare name allows that tool in every app that declares it. Anything not listed is refused.
`allowedTools` and `filter` only narrow what the base policy (`enabledInCodeCall`, `includeTools`,
the blocked namespaces) already allows; listing a tool the base policy withholds does not make it
callable. `filter` receives the same object as `includeTools`.

### 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

A refused call returns a standard `CallToolResult`. The message is the same whether the tool is
withheld or does not exist, so `codecall:invoke` does not reveal which tools the policy hides:

```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "content": [
    { "type": "text", "text": "Tool \"users:delete\" is not available. Use codecall:search to discover available tools." }
  ],
  "isError": true
}
```

### Security Considerations

<Warning>
  Direct invocation bypasses VM security validation. Only enable for tools you trust completely.
</Warning>

* **allowedTools**: Always specify an explicit allowlist in production
* **No script execution**: Direct calls cannot run arbitrary code
* **Same tool access rules**: `codecall:invoke` first applies the policy `codecall:execute` uses (`enabledInCodeCall`, `includeTools`, blocked namespaces); `directCalls` only narrows it
* **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/plugin-codecall';

@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.tags?.includes('destructive')) 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

<Steps>
  <Step title="Add CodeCallPlugin">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    plugins: [
      CodeCallPlugin.init({ mode: 'metadata_driven' }),
    ]
    ```
  </Step>

  <Step title="Mark Tools for CodeCall">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    @Tool({
      codecall: { enabledInCodeCall: true, visibleInListTools: true },
    })
    ```
  </Step>

  <Step title="Test Both Access Methods">
    Verify tools work via both direct calls and CodeCall.
  </Step>

  <Step title="Switch to codecall_only">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    CodeCallPlugin.init({ mode: 'codecall_only' })
    ```
  </Step>

  <Step title="Remove Direct Visibility">
    ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    codecall: { enabledInCodeCall: true, visibleInListTools: false }
    ```
  </Step>
</Steps>

***

## Related

<CardGroup cols={2}>
  <Card title="Security Model" icon="shield" href="/frontmcp/plugins/codecall/security">
    Security implications of configuration choices
  </Card>

  <Card title="Production & Scaling" icon="server" href="/frontmcp/plugins/codecall/production">
    Performance tuning and monitoring
  </Card>

  <Card title="AgentScript Guide" icon="scroll" href="/frontmcp/plugins/codecall/agentscript">
    Scripting language reference and best practices
  </Card>

  <Card title="API Reference" icon="book" href="/frontmcp/plugins/codecall/api-reference">
    Complete meta-tool schemas and examples
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.