<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.7-mcp-integration -->

# MCP Integration

- src/mcp_server/handler.rs
- src/mcp_server/mod.rs
- src/mcp_server/stdio.rs
- src/tools/mcp/client.rs
- src/tools/mcp/discovery.rs
- src/tools/mcp/mod.rs
- src/tools/mcp/transport.rs

## Purpose and Scope

This document describes ZeptoClaw's Model Context Protocol (MCP) integration, which enables dynamic discovery and execution of tools exposed by external MCP servers. ZeptoClaw supports both acting as an **MCP Client** (consuming tools from external servers) and an **MCP Server** (exposing ZeptoClaw's internal tools to other MCP-capable clients like Claude Desktop).

The integration supports **stdio** and **HTTP** transports, implements JSON-RPC 2.0 for communication, and integrates with ZeptoClaw's safety layer, including taint tracking and policy enforcement.

## MCP Client Architecture

ZeptoClaw's MCP client implementation allows agents to access external services and APIs without requiring built-in tool implementations.

### MCP Client Component Structure

```

```

Sources: [src/tools/mcp/mod.rs1-9](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/mod.rs#L1-L9) [src/tools/mcp/client.rs13-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/client.rs#L13-L22) [src/tools/mcp/discovery.rs56-79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/discovery.rs#L56-L79)

### Server Auto-Discovery

ZeptoClaw automatically scans standard locations for MCP server configurations, supporting formats used by Claude Desktop and other ecosystem tools [src/tools/mcp/discovery.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/discovery.rs#L1-L11)

**Discovery Locations:**

1. ~/.mcp/servers.json — Global user-level configuration src/tools/mcp/discovery.rs 59-60
2. {workspace}/.mcp.json — Project-level configuration src/tools/mcp/discovery.rs 67-68

**Supported Transports:**

- Stdio : Launches a child process and communicates via stdin/stdout with Content-Length framing src/tools/mcp/transport.rs 82-84 It uses tokio::process::Command to manage the lifecycle of the external server src/tools/mcp/transport.rs 110-122
- HTTP : Connects to a remote or local URL via POST requests using reqwest src/tools/mcp/transport.rs 27-30

Sources: [src/tools/mcp/discovery.rs18-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/discovery.rs#L18-L53) [src/tools/mcp/transport.rs13-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/transport.rs#L13-L24) [src/tools/mcp/transport.rs104-141](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/transport.rs#L104-L141)

## MCP Server Implementation

ZeptoClaw can expose its own tool registry as an MCP server, allowing external clients to leverage ZeptoClaw's filesystem, shell, and web tools [src/mcp_server/mod.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/mod.rs#L1-L5)

### Request Handling Pipeline

When ZeptoClaw acts as a server, it maps MCP JSON-RPC methods to internal kernel operations via `handle_request` [src/mcp_server/handler.rs40-56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L40-L56)

Sources: [src/mcp_server/handler.rs46-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L46-L51)

### Stdio and HTTP Transports

ZeptoClaw supports two primary server transports:

1. Stdio : The default transport, reading line-delimited JSON-RPC from stdin and writing to stdout src/mcp_server/stdio.rs 1-4 It uses process_line to validate the jsonrpc version and extract the method/ID src/mcp_server/stdio.rs 71-111
2. HTTP : Feature-gated behind panel , this transport uses axum to provide a POST endpoint src/mcp_server/mod.rs 37-38 It uses a channel-based background processor ( mpsc::channel ) to handle requests asynchronously, avoiding lifetime issues with extractors src/mcp_server/mod.rs 58-94

Sources: [src/mcp_server/mod.rs18-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/mod.rs#L18-L31) [src/mcp_server/stdio.rs19-65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/stdio.rs#L19-L65) [src/mcp_server/mod.rs99-170](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/mod.rs#L99-L170)

## Security and Safety Gates

Every tool call initiated via the MCP server (`tools/call`) passes through the standard ZeptoKernel security pipeline [src/mcp_server/handler.rs141-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L141-L150)

### Tool Execution Pipeline (Gated)

```

```

Sources: [src/mcp_server/handler.rs111-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L111-L182) [src/mcp_server/mod.rs91-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/mod.rs#L91-L92)

### ID Preservation and Notifications

The server implementation strictly follows JSON-RPC 2.0:

- ID Preservation : The id is stored as a serde_json::Value to preserve its original type (string, number, or null) src/mcp_server/handler.rs 38-39
- Notifications : Methods starting with notifications/ (or requests missing an id ) are treated as notifications; the server processes them but suppresses the response src/mcp_server/handler.rs 28-30 src/mcp_server/stdio.rs 106-108

Sources: [src/mcp_server/handler.rs40-45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L40-L45) [src/mcp_server/stdio.rs134-142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/stdio.rs#L134-L142)

## Protocol Types

ZeptoClaw implements the MCP JSON-RPC 2.0 schema in `src/tools/mcp/protocol.rs`.

Sources: [src/tools/mcp/protocol.rs1-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/protocol.rs#L1-L133) [src/mcp_server/handler.rs13-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/handler.rs#L13-L16)

## Command Reference

### mcp-server Command

The `mcp-server` command boots a `ZeptoKernel` and starts the `McpServer` instance [src/mcp_server/mod.rs18-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/mcp_server/mod.rs#L18-L20)

- Stdio Mode : Triggered by start_stdio() , blocks until stdin EOF src/mcp_server/mod.rs 29-31
- HTTP Mode : Triggered by start_http(addr) , providing an MCP interface over a network port src/mcp_server/mod.rs 38-51

### Discovery Logic

The `discover_mcp_servers` function returns a list of `DiscoveredMcpServer` objects [src/tools/mcp/discovery.rs56-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/discovery.rs#L56-L57) It prioritizes global config over project-level config [src/tools/mcp/discovery.rs59-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/discovery.rs#L59-L72) Each discovered server is then used by the kernel to instantiate an `McpClient` with the appropriate `McpTransport` [src/tools/mcp/client.rs37-46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/client.rs#L37-L46)

Sources: [src/tools/mcp/mod.rs7-8](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/mod.rs#L7-L8) [src/tools/mcp/client.rs24-34](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/client.rs#L24-L34)

**Sources:**

- src/mcp_server/handler.rs 1-182
- src/mcp_server/stdio.rs 1-142
- src/mcp_server/mod.rs 1-170
- src/tools/mcp/discovery.rs 1-144
- src/tools/mcp/client.rs 1-159
- src/tools/mcp/transport.rs 1-203
- src/tools/mcp/mod.rs 1-9
