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

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 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, agents like Claude Code and Cursor store connection details in their respective MCP configuration files. The 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:

{
  "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:

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

The 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, 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:

# Automatic setup for Claude Code

npx wigolo init --agents=claude-code

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

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

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:

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 – Default MCP configuration schema read by the server during startup.
• 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 – Handles formatting and serialization of JSON responses sent back to agents.
• docs/rest-api.md – Documents the optional HTTP transport layer for remote agent connections.
• 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), process connection, JSON message exchange, result consumption (src/cli/tui/status-agents.ts), and optional HTTP fallback (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 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, 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, 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.

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