Void

Void is a universal no-op MCP server that turns tool calls into freely shaped spaces for thought. Descriptions and input schemas guide what an agent articulates, while configured results can cue recursive in-context self-correction.

Technically, you supply one or more MCP tool definitions as inline JSON or JSON files when launching Void. Each definition freely sets the tool's description and object-rooted input schema, along with its name and fixed result. Void advertises the description and schema unchanged, performs no work with the arguments, and returns the result verbatim. In mutable mode, an agent can create and remove the same kind of tool during the session through void_create_tool and void_remove_tool.

It uses the MCP TypeScript SDK v2 and serves stdio only.

Thinking with Void

examples/universal.json makes the loop explicit:

1. Choose a form that suits the current move: a napkin, decision ledger, glassboard, test sweep, or something invented in the moment.
2. Write the artifact into the tool call.
3. React to that artifact in thinking and visible response text: say what became apparent and what changes because of it.
4. Call Universal again with the improved understanding, continuing until the work settles.

examples/anything.json is the opposite extreme: an unrestricted object-shaped scratch space with no prescribed feedback. Use it when even naming the form would constrain the thought too early.

Tool definitions

Every input source must contain a top-level JSON array. Each item has this shape:

[
  {
    "name": "assumption_check",
    "description": "Stress-test the assumption most likely to break the current approach.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "assumption": {
          "type": "string",
          "description": "The load-bearing assumption."
        },
        "evidence": {
          "type": "string",
          "description": "What currently supports or contradicts it."
        },
        "change": {
          "type": "string",
          "description": "What you will change if it fails."
        }
      },
      "required": ["assumption", "evidence", "change"]
    },
    "result": "Now revise the approach around what you found."
  }
]

description is optional. name, inputSchema, and result are required. Tool names follow MCP's 1–128 character A-Z, a-z, 0-9, _, -, and . convention. An empty result string is valid.

The input schema is checked before the tool is registered and then advertised unchanged through tools/list. Void deliberately does not validate custom tool calls against it. Arguments that violate the advertised schema still receive the configured result.

Run

Pass one or more inline arrays, JSON files, or a mixture. Void concatenates their definitions in argument order and rejects duplicate names before starting the protocol transport. At least one definition source is required unless --mutable is enabled.

void-mcp ./base-tools.json ./project-tools.json '[{"name":"nope","inputSchema":{"type":"object"},"result":"Nope."}]'

Stdout belongs exclusively to MCP JSON-RPC. Startup errors and diagnostics go to stderr.

Claude Code

After running pnpm build, add a project-scoped .mcp.json and replace /absolute/path/to/void-mcp with this repository's absolute path:

{
  "mcpServers": {
    "void": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/void-mcp/dist/src/cli.js",
        "/absolute/path/to/void-mcp/examples/universal.json"
      ]
    }
  }
}

Claude Code asks for approval before using a project-scoped MCP server. Open /mcp to inspect the connection and exposed Universal tool.

Live tools

Add --mutable to expose two management tools:

• void_create_tool invites the agent to invent and register a new thinking tool for the lifetime of the server process.
• void_remove_tool removes an ordinary tool present in the current session, whether loaded at startup or created live.

void-mcp --mutable

Mutable mode can start without any definition sources because its management tools can populate the server after startup. You can still pass startup definitions when useful. Created tools are ephemeral: an agent can try a first version, use it, remove it, and invent a better one without persisting the definition.

Creating or removing a tool emits notifications/tools/list_changed through the SDK. Management tools validate their own arguments because they mutate server state. They are reserved and cannot remove themselves.

Some clients expose a newly created tool only after the next turn boundary. This is client discovery behavior; the server registers the tool immediately.

For protocol debugging, --debug-log <file> appends structured JSONL events without writing to MCP stdout. The trace includes schemas and tool names, but only argument keys and configured-result lengths—not custom call values or result text.

void-mcp --mutable --debug-log ~/tmp/void-mcp/claude-code.jsonl ./tools.json

Without --mutable, neither management tool is exposed.

Development

pnpm install

pnpm check