MCP servers (host-injectable)

Core loads MCP servers only from an LM Studio–compatible mcp.json.
Hosts (Desktop, IDEs, etc.) own the UI; Core merges and bridges tools.
Overview: host_integrations.md.

local-ai-mcp is a hard dependency of local-ai-core.

Behavior

• Lazy connect — stdio subprocess or HTTP session starts on first tool use

(or at startup() when discovering tools for allowed_tools: ["*"] / empty).

• Transports:
• stdio: command / args / env
• HTTP: url / headers (Streamable HTTP; SSE fallback)
• Tool names: mcp_{server_id}_{tool_name} (sanitized).
• Log events: MCP_CONNECT, MCP_DISCOVER, MCP_TOOL_CALL, MCP_ERROR.

mcp.json (sole server source)

Default path: {runtime_data_dir}/mcp.json.

Override: mcp.external_path in config.yaml, CLI --mcp-config, or env
LOCAL_AI_MCP_CONFIG.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/path"],
      "env": {},
      "allowed_tools": ["*"],
      "requires_approval": false,
      "timeout_seconds": 60
    },
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "..."
      }
    }
  }
}

• allowed_tools: ["*"] or omitted/empty → discover all tools at startup().
• Explicit list → only those tools are registered (still lazy-connect on call).
• Entries with neither command nor url are skipped with MCP_ERROR.

config.yaml (path only)

YAML does not define servers. It may only point at the JSON file:

mcp:
  enabled: false          # set true automatically when mcp.json has servers
  external_path: null     # default: {runtime_data_dir}/mcp.json

Agent allowlist

mcp_ tools are auto-granted to agents (no need to list every name under
agents..tools).

Native tools (not MCP)

Always-on when their infra is enabled:

• report_inability — always registered
• load_message — message archive
• load_tool_result / search_tool_results — memory L3