Wigolo MCP Server Mode vs REST API Mode: Key Differences and When to Use Each

Wigolo exposes its ten-tool suite (search, fetch, crawl, extract, and more) through either JSON-RPC over stdio for MCP-compatible agents or plain HTTP endpoints for general-purpose clients, with the former requiring no authentication for local use and the latter enforcing Bearer token security on non-loopback interfaces.

The KnockOutEZ/wigolo repository provides a versatile web interaction toolkit that can operate as both a local Model Context Protocol (MCP) server and a standalone REST API service. Understanding the architectural distinctions between wigolo MCP server mode vs REST API mode helps developers choose the right integration strategy for coding agents, automation scripts, or microservice deployments.

Transport Layer and Protocol Architecture

MCP Server Mode: JSON-RPC over Stdio

In MCP server mode, wigolo communicates via JSON-RPC over stdio, where the process reads and writes JSON-RPC frames directly through standard input and output streams. This transport mechanism, implemented in src/cli/mcp.ts and launched through mcpb/server/index.cjs, enables tight integration with MCP-compatible coding agents like Claude Code, Cursor, and VS Code extensions. The protocol eliminates network overhead for local tool execution, making it ideal for development environments where the daemon and agent run side-by-side.

REST API Mode: HTTP with OpenAPI

REST API mode operates over standard HTTP with a plain-JSON contract, exposing endpoints such as POST /v1/search through the server defined in src/daemon/http-server.ts. This mode serves an OpenAPI 3.1 specification at GET /openapi.json (documented in docs/rest-api.md), enabling automatic client generation and discovery for any HTTP-capable consumer. The HTTP server lazily constructs its router and supports both traditional request/response patterns and advanced streaming capabilities.

Authentication and Security Models

Security boundaries differ fundamentally between the two modes. The MCP server mode requires no authentication tokens for the local stdio channel because the client and server exist within the same process boundary. Conversely, REST API mode operates with a "fails closed" security model: when binding to loopback addresses (127.0.0.1), the server remains open, but non-loopback interfaces require a Bearer token passed via the --token flag. This distinction makes MCP mode optimal for trusted local development while REST mode safely supports remote deployments.

Entry Points and Client Integration

The initiation patterns reflect the architectural intentions of each mode.

MCP Server Mode starts via:

wigolo mcp

Or through the thin launcher at mcpb/server/index.cjs that executes npx wigolo mcp. Clients discover tool shapes through the MCP registry (io.github.KnockOutEZ/wigolo) and fetch schemas via the MCP handshake protocol.

REST API Mode begins with:

wigolo serve --host 0.0.0.0 --token $WIGOLO_API_TOKEN

This command starts the HTTP server defined in src/daemon/http-server.ts, which hosts not only the REST endpoints but also a /mcp endpoint for remote MCP clients and an /sse route for Server-Sent Events streaming.

Streaming and Real-Time Capabilities

Both modes support streaming, but through different mechanisms. MCP server mode leverages Server-Sent Events (SSE) via the /sse endpoint mounted on the same port as the HTTP server, enabling incremental updates without traditional HTTP polling. REST API mode primarily uses standard HTTP streaming such as chunked responses, though it maintains request/response semantics as the primary contract. The SSE capability in MCP mode provides more efficient real-time updates for long-running operations like web crawling or extraction tasks.

Practical Usage Examples

Running the MCP server locally:

# Start JSON-RPC over stdio

wigolo mcp

# Or via the npm launcher used by distributed packages

npx -y wigolo mcp

Consuming tools via TypeScript SDK:

import { createLocalClient } from 'wigolo-sdk/local';

const { client, close } = await createLocalClient();
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map(r => r.title));
await close();

Starting the REST API server:

# Local development (loopback open)

wigolo serve

# Remote deployment with authentication

wigolo serve --host 0.0.0.0 --token $WIGOLO_API_TOKEN

Calling the REST API directly:

curl -sX POST http://127.0.0.1:3333/v1/search \
     -H 'Content-Type: application/json' \
     -d '{"query":"local-first software","max_results":5}'

Accessing the MCP endpoint over HTTP:

curl -sX POST http://127.0.0.1:3333/mcp \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","method":"search","params":{"query":"..."},"id":1}'

Summary

• Transport: MCP uses JSON-RPC over stdio; REST uses HTTP with OpenAPI 3.1 discovery.
• Security: MCP requires no tokens for local stdio; REST enforces Bearer tokens on non-loopback interfaces as implemented in src/daemon/http-server.ts.
• Entry Points: Launch MCP via wigolo mcp or mcpb/server/index.cjs; start REST via wigolo serve.
• Clients: MCP targets coding agents and IDE integrations; REST targets general HTTP clients, browsers, and webhooks.
• Streaming: Both support real-time updates, with MCP offering native SSE and REST providing chunked HTTP responses.

Frequently Asked Questions

Can I use both MCP and REST modes simultaneously?

No, you must choose the transport layer at startup. Run wigolo mcp for stdio-based JSON-RPC communication or wigolo serve for HTTP-based access. However, the REST server exposes a /mcp endpoint that wraps MCP protocol over HTTP, allowing remote MCP clients to connect via the HTTP transport while the server runs in REST mode.

How does authentication work in MCP server mode?

MCP server mode operates without authentication tokens because it uses stdio transport within a single process boundary. The security model assumes the client (such as Claude Code or Cursor) is trusted code running on the same machine, eliminating the need for Bearer tokens or API keys that REST mode requires for remote network interfaces.

Which mode should I choose for CI/CD pipelines?

Use REST API mode for CI/CD environments. The HTTP interface accepts standard curl commands and integrates with existing pipeline tools that do not implement MCP clients. Configure authentication with the --token flag when binding to network interfaces beyond localhost, as implemented in src/daemon/http-server.ts.

Where is the OpenAPI specification hosted?

The REST API serves an OpenAPI 3.1 document at GET /openapi.json on the server started by wigolo serve. This endpoint, defined in the HTTP server implementation and documented in docs/rest-api.md, provides the complete contract for all ten tools including search, fetch, crawl, and extract operations, enabling automatic client generation in any programming language.

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