How to Integrate Kimi CLI with Other Tools: MCP Servers, Custom Python Tools, and Sub-Agents

You can integrate Kimi CLI with external tools through three main mechanisms: MCP (Multi-Channel Protocol) servers for remote services, custom Python tools via the Tool subclass system, and sub-agents that run as persistent child sessions.

Kimi CLI is a modular command-line interface developed by MoonshotAI that supports flexible integration with external services and custom logic. If you need to integrate kimi-cli with other tools, the codebase provides three distinct extension points centered around the Toolset architecture defined in src/kimi_cli/soul/toolset.py.

Three Methods to Integrate Kimi CLI with Other Tools

MCP (Multi-Channel Protocol) Servers

The MCP integration method allows any service to expose LLM-compatible tools over HTTP or WebSocket using FastMCP. Kimi CLI automatically discovers these servers and forwards tool calls to them during conversations.

In src/kimi_cli/soul/toolset.py, the runtime imports and uses fastmcp for remote tool calls. The CLI management interface lives in src/kimi_cli/cli/mcp.py, which handles adding, listing, and removing MCP servers. Wire protocol messages like MCPServerSnapshot and MCPStatusSnapshot are defined in src/kimi_cli/wire/types.py to report loading status in the UI.

Custom Python Tools

Any Python module placed under src/kimi_cli/tools/ that exports a Tool subclass (or uses the @Tool decorator) becomes immediately loadable by the agent system. The Toolset class in src/kimi_cli/soul/toolset.py loads these classes, injects dependencies, and makes them callable from the LLM.

Agent specifications reference these tools via import paths (e.g., kimi_cli.tools.my_tool.MyTool). The package entry point for built-in tools is src/kimi_cli/tools/__init__.py.

Sub-Agents for Complex Workflows

Sub-agents run as independent Kimi CLI sessions that can be addressed via the /agent:<name> slash command or directly from a tool. They communicate through the same wire protocol, letting you embed secondary LLM-driven workflows inside the primary session.

Sub-agent registration and creation logic resides in src/kimi_cli/soul/agent.py. YAML agent specifications in src/kimi_cli/agents/ can extend other agents and declare extra tools for these child sessions.

Step-by-Step Integration Examples

Adding an MCP Server

First, expose your remote tool using FastMCP:

# fastmcp_server.py

from fastmcp import FastMCP, register_tool

@register_tool(name="weather")
async def get_weather(city: str) -> str:
    # ... fetch weather …

    return f"The weather in {city} is sunny."

server = FastMCP("my-weather")
server.run(host="0.0.0.0", port=8000)

After starting the server, add it to Kimi CLI:

$ kimi mcp add my-weather http://localhost:8000

Manage your MCP configurations:

# List current MCP configuration

kimi mcp list

# Remove a server

kimi mcp remove example

Creating a Custom Python Tool

Create a new tool file in the tools directory:

# src/kimi_cli/tools/weather_tool.py

from kosong.tooling import CallableTool
from typing import Literal

class GetWeather(CallableTool):
    """Return a short weather summary for a city."""
    async def __call__(self, city: str) -> str:
        # simple static example; replace with a real API call

        return f"The weather in {city} is cloudy."

Alternative example using a simple text transformation:

# src/kimi_cli/tools/uppercase.py

from kosong.tooling import CallableTool

class UpperCase(CallableTool):
    """Return the uppercase version of the input string."""
    async def __call__(self, text: str) -> str:
        return text.upper()

Configuring Agent Specifications

Reference your custom tool in a YAML agent spec:

# src/kimi_cli/agents/custom.yml

name: custom-agent
tools:
  - import_path: kimi_cli.tools.weather_tool.GetWeather

Or for the uppercase tool:

# src/kimi_cli/agents/uppercase.yml

name: uppercase-agent
tools:
  - import_path: kimi_cli.tools.uppercase.UpperCase

Run Kimi CLI with your custom agent:

$ kimi --agent custom-agent

Now you can ask the LLM:

> What's the weather in Paris?

The LLM issues a tool call to GetWeather, and Kimi CLI returns the result directly in the chat.

Registering Sub-Agents

Create a persistent child agent for complex workflows:

$ kimi /agent:create my-subagent --spec custom-agent

Address the sub-agent from your main session:

> /agent:my-subagent ask it to summarize the last 10 messages.

Key Source Files for Integration

Understanding these core files helps when building custom integrations:

• src/kimi_cli/soul/toolset.py – Core loader for both built-in and MCP tools. Handles class instantiation and dependency injection.
• src/kimi_cli/cli/mcp.py – CLI helpers for managing MCP server entries via the kimi mcp command group.
• src/kimi_cli/wire/types.py – Wire-protocol messages including MCPServerSnapshot and MCPStatusSnapshot that report MCP loading status in the UI.
• src/kimi_cli/tools/ – Directory containing built-in tool implementations (e.g., shell, file, web).
• src/kimi_cli/agents/ – YAML specifications where you declare which tools an agent should expose.
• src/kimi_cli/soul/agent.py – Registers and creates sub-agents for nested workflow support.

Summary

• MCP servers provide HTTP/WebSocket-based integration for remote services using FastMCP, managed via src/kimi_cli/cli/mcp.py.
• Custom Python tools require subclassing CallableTool or using the @Tool decorator, placing modules in src/kimi_cli/tools/ for automatic discovery by the Toolset loader.
• Sub-agents enable persistent child sessions accessible via /agent:<name> commands, implemented in src/kimi_cli/soul/agent.py.
• Agent specifications use YAML files in src/kimi_cli/agents/ to declare which tools are available for specific workflows.

Frequently Asked Questions

Can I use existing FastMCP servers without modifying Kimi CLI source code?

Yes. According to the source code in src/kimi_cli/cli/mcp.py, you can add any FastMCP-compliant server using the kimi mcp add <name> <url> command. The runtime in src/kimi_cli/soul/toolset.py automatically discovers and forwards tool calls to these endpoints without requiring changes to the core codebase.

What is the difference between a Tool and a CallableTool in Kimi CLI?

The source code analysis shows that custom Python tools can be created by subclassing CallableTool from kosong.tooling or by using the @Tool decorator. Both approaches export a callable that the Toolset loader can instantiate. CallableTool provides an async __call__ interface that the LLM invokes when making tool calls during conversations.

How do sub-agents communicate with the main Kimi CLI session?

Sub-agents communicate through the same wire protocol used by the main session, as implemented in src/kimi_cli/soul/agent.py. They run as independent Kimi CLI sessions that can be addressed via the /agent:<name> slash command or directly invoked from tools, allowing seamless embedding of secondary LLM-driven workflows within your primary chat interface.

Where should I place custom tool definitions to ensure they load automatically?

Place any Python module containing a Tool subclass under src/kimi_cli/tools/ and reference it in your agent YAML spec using the full import path (e.g., kimi_cli.tools.my_tool.MyTool). The Toolset class in src/kimi_cli/soul/toolset.py scans this directory and handles dependency injection when the agent initializes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}