# How the Wigolo MCP Server Communicates with AI Agents: A Technical Deep Dive

> Discover how the wigolo MCP server communicates with AI agents like Claude Code and Cursor using a stdio-based JSON protocol. Learn about child process spawning and MCP message exchange over stdin/stdout.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: deep-dive
- Published: 2026-07-29

---

**Wigolo communicates with AI agents like Claude Code and Cursor via a stdio-based JSON protocol, where the agent spawns the wigolo process as a child and exchanges Model Control Protocol (MCP) messages over stdin/stdout.**

The KnockOutEZ/wigolo repository implements a local MCP (Model Control Protocol) server that enables AI agents to perform web search, crawling, and data extraction. Understanding how the wigolo MCP server communicates with AI agents reveals a lightweight architecture built on standard I/O streams and JSON-encoded RPC-style messaging that works across any MCP-capable client.

## The MCP Protocol Foundation

Wigolo ships a **local MCP (Model-Control-Protocol) server** that conforms to the MCP specification for tool integration. Rather than using network sockets or complex binary protocols, the server relies on **stdio transport**—reading from `stdin` and writing to `stdout`—to exchange JSON messages with the parent AI agent process. This design ensures compatibility with any agent that supports the MCP standard, including Claude Code, Cursor, VS Code, Zed, and OpenCode.

## Step-by-Step Communication Flow

### Server Initialization

When wigolo starts in MCP mode, it executes `mcpb/server/index.cjs`, which reads its configuration from [`mcp.json`](https://github.com/KnockOutEZ/wigolo/blob/main/mcp.json) and initializes the stdio listener. This file serves as the entry point for all MCP interactions, setting up the message parser and routing logic that will handle incoming requests from AI agents.

### Agent Configuration and Wiring

Before communication begins, the user must register wigolo as an MCP client. According to the source in [`site/public/llms.txt`](https://github.com/KnockOutEZ/wigolo/blob/main/site/public/llms.txt), agents like **Claude Code** and **Cursor** store connection details in their respective MCP configuration files. The [`src/cli/tui/config-writer-cli.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/config-writer-cli.ts) module handles the CLI-side logic for writing these entries, typically storing the spawn command `["npx", "-y", "wigolo"]` so the agent knows how to launch the server.

### Process Connection via Stdio

When an agent needs to use a wigolo tool, it spawns the process defined in its configuration. The two processes become attached via **stdin/stdout pipes**, creating a persistent communication channel. This connection remains active for the duration of the tool invocation, with the agent acting as the client and wigolo as the server.

### JSON Message Exchange

Once connected, both sides exchange **JSON-encoded MCP messages** following a strict request-response pattern. The agent sends payloads like:

```json
{
  "type": "request",
  "id": "1",
  "method": "search",
  "params": {
    "query": "latest TypeScript release",
    "topK": 5
  }
}

```

Wigolo parses this message, executes the requested operation (search, fetch, extract, etc.), and writes back a response to stdout:

```json
{
  "type": "response",
  "id": "1",
  "result": {
    "results": [...]
  }
}

```

The [`src/cli/tui/status-agents.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/status-agents.ts) file contains the formatting logic that prepares these responses for agent consumption.

### Optional HTTP REST Endpoint

While stdio is the primary transport, wigolo also exposes a **REST API** for agents that prefer HTTP communication. As documented in [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md), the remote endpoint (`/api/...`) forwards the same MCP-style JSON payloads to the local server, allowing network-based agents to utilize the same toolset without process spawning.

## Implementation Details and Code Examples

To establish communication manually, you can wire wigolo into Claude Code using the initialization command:

```bash

# Automatic setup for Claude Code

npx wigolo init --agents=claude-code

```

For Cursor or other agents, use the MCP add command:

```bash

# Manual registration with Cursor

cursor mcp add wigolo --scope user -- npx -y wigolo

```

When implementing a custom agent client, the stdio communication follows this TypeScript pattern:

```typescript
import { spawn } from 'child_process';

// Spawn the wigolo MCP server
const wigolo = spawn('npx', ['-y', 'wigolo'], {
  stdio: ['pipe', 'pipe', 'pipe']
});

// Send a search request
wigolo.stdin.write(JSON.stringify({
  type: "request",
  id: "42",
  method: "search",
  params: { query: "wigolo documentation", topK: 3 }
}) + "\n");

// Receive the response
wigolo.stdout.on("data", (chunk) => {
  const resp = JSON.parse(chunk.toString());
  console.log("Results:", resp.result);
});

```

For HTTP-based integration, post to the REST endpoint:

```typescript
import fetch from 'node-fetch';

const response = await fetch("http://localhost:3000/api/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "request",
    id: "101",
    method: "search",
    params: { query: "MCP protocol spec", topK: 5 }
  })
});

const data = await response.json();
console.log(data.result);

```

## Key Source Files

Understanding the communication flow requires familiarity with these specific files in the KnockOutEZ/wigolo repository:

- **`mcpb/server/index.cjs`** – Entry point for the local stdio MCP server that initializes the JSON protocol handler.
- **[`mcp.json`](https://github.com/KnockOutEZ/wigolo/blob/main/mcp.json)** – Default MCP configuration schema read by the server during startup.
- **[`src/cli/tui/config-writer-cli.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/config-writer-cli.ts)** – CLI helper that writes MCP configuration entries for agents when running `wigolo init`.
- **[`src/cli/tui/status-agents.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/status-agents.ts)** – Handles formatting and serialization of JSON responses sent back to agents.
- **[`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md)** – Documents the optional HTTP transport layer for remote agent connections.
- **[`site/public/llms.txt`](https://github.com/KnockOutEZ/wigolo/blob/main/site/public/llms.txt)** – Lists supported agents and command syntax for manual MCP setup.

## Summary

- Wigolo implements an MCP server that communicates via **stdio-based JSON messaging**, allowing AI agents to spawn and control the process directly.
- The communication flow involves **six distinct phases**: server startup (`mcpb/server/index.cjs`), agent wiring ([`site/public/llms.txt`](https://github.com/KnockOutEZ/wigolo/blob/main/site/public/llms.txt)), process connection, JSON message exchange, result consumption ([`src/cli/tui/status-agents.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/status-agents.ts)), and optional HTTP fallback ([`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md)).
- Agents like **Claude Code** and **Cursor** register wigolo by storing the spawn command `npx -y wigolo` in their MCP configuration files.
- Messages follow a strict JSON schema with `type`, `id`, `method`, and `params` fields for requests, and corresponding `result` or `error` fields for responses.
- The **REST API endpoint** provides an alternative transport for network-based agents that cannot use stdio, using the same JSON message format over HTTP POST requests.

## Frequently Asked Questions

### What transport protocol does wigolo use for MCP communication?

Wigolo primarily uses **stdio transport** (standard input/output) for MCP communication, where the AI agent spawns wigolo as a child process and exchanges JSON messages over `stdin` and `stdout`. According to the source in `mcpb/server/index.cjs`, the server initializes a stdio listener that parses incoming JSON-RPC-style messages and routes them to the appropriate tool handlers.

### Can wigolo communicate with AI agents other than Claude Code and Cursor?

Yes. Because wigolo implements the standard **Model Control Protocol (MCP)** using JSON over stdio, any MCP-capable agent can connect to it. The [`site/public/llms.txt`](https://github.com/KnockOutEZ/wigolo/blob/main/site/public/llms.txt) file explicitly mentions support for VS Code, Zed, and OpenCode, and the stdio-based design means any client that can spawn processes and parse JSON can integrate with the server.

### Where does wigolo handle the JSON message parsing in the codebase?

The MCP server entry point in `mcpb/server/index.cjs` handles the initial JSON message parsing and protocol handshake. For CLI-specific MCP interactions, such as configuration writing, the logic resides in [`src/cli/tui/config-writer-cli.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/tui/config-writer-cli.ts), which prepares the server environment before message exchange begins.

### How do I switch from stdio to HTTP for wigolo MCP communication?

To use HTTP instead of stdio, start the wigolo server with the REST API enabled and POST MCP-formatted JSON payloads to the `/api/mcp` endpoint. As documented in [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md), the HTTP endpoint accepts the same JSON message structure used in stdio mode, forwarding requests to the internal MCP handler and returning JSON responses over the HTTP connection.