Configuration - AgentFront

This page covers all configuration options for the CodeCall plugin, from quick presets to fine-grained control.

Plugin Initialization

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.

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.

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.

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:

@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

Hide from list_tools, available in CodeCall

codecall: {
  enabledInCodeCall: true,
  visibleInListTools: false,
}

Use for: Most tools in codecall_only mode.

Visible everywhere

codecall: {
  enabledInCodeCall: true,
  visibleInListTools: true,
}

Use for: Core tools that should be directly accessible AND in CodeCall.

Direct access only, no CodeCall

codecall: {
  enabledInCodeCall: false,
  visibleInListTools: true,
}

Use for: Admin tools, destructive operations, tools requiring human review.

CodeCall meta-tools only

codecall: {
  enabledInCodeCall: false,
  visibleInListTools: true,
}

Applied automatically to codecall:search, codecall:describe, etc.

Global Tool Filtering

Filter tools globally with includeTools:

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:

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:

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

locked_down
secure
balanced
experimental

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

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

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

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

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.

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

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:

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

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

embedding: {
  strategy: 'ml',
  modelName: 'Xenova/all-MiniLM-L6-v2',  // Default
  cacheDir: './.cache/transformers',
  useHNSW: true,  // For large toolsets (1000+)
}

ML strategy uses 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:

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:

{
  "content": [
    { "type": "text", "text": "Tool \"users:delete\" is not available. Use codecall:search to discover available tools." }
  ],
  "isError": true
}

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

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

Add CodeCallPlugin

plugins: [
  CodeCallPlugin.init({ mode: 'metadata_driven' }),
]

Mark Tools for CodeCall

@Tool({
  codecall: { enabledInCodeCall: true, visibleInListTools: true },
})

Test Both Access Methods

Verify tools work via both direct calls and CodeCall.

Switch to codecall_only

CodeCallPlugin.init({ mode: 'codecall_only' })

Remove Direct Visibility

codecall: { enabledInCodeCall: true, visibleInListTools: false }

Security Model

Security implications of configuration choices

Production & Scaling

Performance tuning and monitoring

AgentScript Guide

Scripting language reference and best practices

API Reference

Complete meta-tool schemas and examples

​Plugin Initialization

​Tool Visibility Modes

​codecall_only (Recommended)

​codecall_opt_in

​metadata_driven

​Per-Tool Metadata

​Metadata by Mode

​Common Patterns

​Global Tool Filtering

​VM Configuration

​VM Presets

​Preset Details

​Reference Sidecar Configuration (Pass-by-Reference)

​Sidecar Presets by Security Level

​How Pass-by-Reference Works

​Embedding Configuration

​Strategy Comparison

​TF-IDF Configuration

​ML Configuration

​Direct Invocation

​When to Use Direct Invoke

​Performance Comparison

​Error Response Format

​Security Considerations

​Complete Configuration Example

​Migration Guide

​From Direct Tools to CodeCall

​Related

Security Model

Production & Scaling

AgentScript Guide

API Reference

Plugin Initialization

Tool Visibility Modes

`codecall_only` (Recommended)

`codecall_opt_in`

`metadata_driven`

Per-Tool Metadata

Metadata by Mode

Common Patterns

Global Tool Filtering

VM Configuration

VM Presets

Preset Details

Reference Sidecar Configuration (Pass-by-Reference)

Sidecar Presets by Security Level

How Pass-by-Reference Works

Embedding Configuration

Strategy Comparison

TF-IDF Configuration

ML Configuration

Direct Invocation

When to Use Direct Invoke

Performance Comparison

Error Response Format

Security Considerations

Complete Configuration Example

Migration Guide

From Direct Tools to CodeCall

Related