Profiles, code mode, and MCP

A CLI profile is the saved configuration for Kestrel's runtime policy, environment binding, model, tools, code execution, reasoning, and MCP servers. Kestrel exposes one canonical profile and agent identity: kestrel.

Select it explicitly with --profile kestrel. profiles.json V10 stores one canonical profile definition plus environment-specific bindings. Alternate profile and agent identities are not supported.

Older V2-V9 files are migrated automatically. Kestrel writes a byte-for-byte backup and a migration report, retains supported managed Kestrel settings, and omits legacy or custom profile authority. Use /profiles and /status to inspect the resolved configuration after migration.

Provider registry and capability readiness

The profile resolves a versioned provider-registry entry and model whose qualified capabilities satisfy its requirements. Configured, reachable, compatible, and qualified are separate readiness states.

Tools and code mode

toolAllowlist narrows the tools available to the profile. Code mode adds controlled code-execution configuration and its required capabilities. Inspect or change it interactively with:

Text

/code status
/code policy
/code enable
/code disable

Use code mode only when the task needs execution. Filesystem, shell, network, and dependency-install behavior remain governed by the configured sandbox and approval policy.

Tool descriptor and invocation rules

Every visible tool uses a canonical descriptor and model-visible input contract. Activation comes from profile, Environment/workspace, MCP, network, and approval policy. Validate arguments before invocation and shape errors without leaking secrets.

Reasoning policy

The reasoning field separates provider reasoning requests from retention. live_only is the default retention mode. Provider-visible reasoning can be retained only when explicitly configured, and retained content is encrypted for the configured window. Provider continuation state is not rendered as visible reasoning.

MCP servers

Profiles can expose local or remote MCP servers. The interactive commands cover server discovery, tool inspection, connection configuration, and allowlisting:

Text

/mcp status
/mcp servers
/mcp tools [serverId]
/mcp add stdio <id> <command> [args...]
/mcp add http <id> <url> [--auth-env VAR] [--header-env Name=ENV]
/mcp add sse <id> <url> [--auth-env VAR] [--header-env Name=ENV]
/mcp allow <toolId>
/mcp deny <toolId>
/mcp remove <serverId>
/mcp refresh

MCP authentication values should be referenced through environment variables, not placed directly in a profile committed to source control.

Only enable MCP servers you trust. Network policy distinguishes isolated/default-deny egress from explicitly approved unrestricted access; container isolation alone does not authorize destinations. OCI services receive only the credentials and mounted data explicitly included in their configuration.

OAuth, grants, and approvals

OAuth connection proves a credential relationship, not permission for every effect. Resolve user/workspace grants and bind external approval to the exact requested action immediately before invocation.

Troubleshooting

Inspect profile revision, provider readiness/capabilities, tool descriptor, MCP health, network mode, credential owner, pending approval, and terminal result in that order.

Read CLI terminal client for using a profile in a session and Command suite for platform state locations.