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

> Integrate Kimi CLI with MCP servers, custom Python tools, and sub-agents. Discover how to extend Kimi CLI's capabilities for seamless workflow automation.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-25

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```python

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

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

```

Manage your MCP configurations:

```bash

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

```python

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

```python

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

```yaml

# src/kimi_cli/agents/custom.yml

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

```

Or for the uppercase tool:

```yaml

# src/kimi_cli/agents/uppercase.yml

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

```

Run Kimi CLI with your custom agent:

```bash
$ kimi --agent custom-agent

```

Now you can ask the LLM:

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

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

```

Address the sub-agent from your main session:

```text
> /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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py) scans this directory and handles dependency injection when the agent initializes.