Model Enhancement Servers

Based on MCP Protocol Version: 2025-06-18

Overview

Model enhancement servers are a specialized category of MCP servers that extend LLM capabilities not by wrapping external APIs, but by providing structured reasoning frameworks, persistence mechanisms, and cognitive workflow guidance.

Wrapper Servers vs. Model Enhancement Servers

Wrapper servers are like keys that open specific chests with specific treasures. They provide access to external services (Supabase, Gmail, Airtable) and are essential for integrating LLMs with existing systems.

Model enhancement servers are like pen and paper: general-purpose cognitive tools natively designed for LLM use. They extend the model's abilities across a variety of circumstances, not just specific API integrations.

Think of model enhancement servers as a bullet journal for AI. The model documents information with the server, which does basic heuristic processing to signal completion of steps and define next scopes. By directing the AI to consider only a small set of concerns during ongoing transactions, performance improves in tasks requiring memory, reasoning, and runtime lookup.

The Context Window Benefit

Similar to how Getting Things Done (GTD) helps humans by offloading thoughts into documents, model enhancement servers help LLMs process more effectively. When we write down one thought instead of juggling a hundred, we can focus better. Context window management is critical to all entities that use attention—a scarce resource.

"Do Nothing" as a core feature of Model Enhancement Servers

A model enhancement server does not do anything, any more than a real bullet journal "does" anything: its value is entirely tied to how well it facilitates the agentic process it's meant to support.

Instead, the server "enhances" an agent's capabilities by externalizing some state that represents the agent's thinking process. As mentioned above, this externalized state allows the agent to focus on the current step. But further, because a representation of reasoning is lossy relative to the actual process of reasoning, creating the representation forces an agent to make choices about what is and is not important to the process: in this way, externalization can be modeled as a form of compression. Just as a human may improve their thinking through journaling or other forms of externalization, agents can improve their reasoning through externalization: the benefits of externalization are not confined to the carbon substrate.

⚠️ CRITICAL PRINCIPLE: The Server Does NOT Reason

The most important thing to understand about model enhancement servers:

The agent performs reasoning. The server provides structure.

Model enhancement servers are scaffolding, not reasoning engines. They are persistence mechanisms and workflow guides, not AI models themselves.

What the server does:

✅ Records reasoning steps (journaling)
✅ Maintains state and history
✅ Validates input format
✅ Returns metadata and progress indicators
✅ Simplifies the possibility space available to the agent
✅ Encourages use of structured workflows
✅ Makes the process transparent and evaluable

What the server does NOT do:

❌ Generate thoughts or reasoning
❌ Decide what the next step should be
❌ Evaluate the quality of the agent's reasoning
❌ Make decisions about problem-solving approaches
❌ Act as an autonomous agent
❌ Perform any AI inference

Why This Matters

The value of model enhancement comes from:

Simplifying possibility space: Fewer choices → better focus
Encouraging structured workflows: Patterns that can be evaluated and improved
Making processes transparent: We (and the agent) can see and analyze what the agent did
Providing persistence: The agent doesn't lose context

The server is a notebook, a journal, a whiteboard—not a tutor, not a critic, not a collaborator.

Remember: The MCP client application (the agent) does the thinking. Your server just keeps the whiteboard clean and organized.

Core Patterns

1. Structured Journal Pattern

Purpose: Track and persist a sequence of reasoning steps while guiding the model through a cognitive process.

Key Features:

Single tool with rich, descriptive guidance in the tool description
State tracking (history of steps, branches, revisions)
Support for non-linear thinking (revisions, branches, adjusting scope)
Dual output channels (structured JSON for model, formatted logs for humans)

When to Use:

Breaking down complex problems into steps
Planning and design requiring iteration
Analysis that might need course correction
Problems where scope isn't fully known upfront
Tasks requiring context maintenance across multiple steps

Example: Sequential Thinking Server

This server provides a framework for step-by-step reasoning with the ability to revise, branch, and adjust course.

Architecture:

interface ThoughtData {
  thought: string;
  thoughtNumber: number;
  totalThoughts: number;
  isRevision?: boolean;
  revisesThought?: number;
  branchFromThought?: number;
  branchId?: string;
  needsMoreThoughts?: boolean;
  nextThoughtNeeded: boolean;
}

Tool Design:

Name: Single, clear tool name (e.g., sequentialthinking)
Description: Extensive guidance on when to use, how it works, parameter meanings, key features, workflow recommendations
Input Schema: Mix of required (core workflow) and optional (advanced features) fields
State Management: Maintain history array, track branches separately, validate input, return status and metadata
Output Strategy: JSON for model, formatted colored display for humans (stderr)

Variations: The Structured Journal pattern can be specialized for specific methodologies:

Structured Argumentation: Typed workflow states (thesis, antithesis, synthesis), relationship graphs, methodology-aware suggestions
Analogical Reasoning: Complex nested structures (source/target domains), multi-instance state tracking, rich metadata summaries

Novel Strategies:

Typed Workflow States: Use enums to make methodology steps explicit
Relationship Tracking: Maintain graphs of how entries relate
Auto-ID Generation: Reduce agent cognitive load
Confidence/Strength Metadata: Let agents express uncertainty numerically
Complex Nested Structures: Support domain-specific decomposition
Methodology-Aware Guidance: Suggest next steps based on formal structure
Multi-Instance Registries: Enable building on previous work
Rich State Summaries: Return contextual metadata about current state

2. Literate Reasoning / Notebook Pattern

Purpose: Provide a Jupyter-like notebook interface where models work through problems with full transparency and reproducibility.

Key Features:

Markdown cells for explanations and reasoning
Code cells for executable actions
Cell-by-cell execution with visible outputs
Re-runnable and modifiable workflows
Living documentation of problem-solving process

When to Use:

Complex multi-step processes requiring transparency
Debugging and tracing agent reasoning
Iterative problem-solving where you might modify approaches
Creating reusable workflow templates ("notebook presets")
Situations where the process matters as much as the result

The Problem It Solves:

Traditional agent interactions are "black boxes" - you get a final answer but don't see how the agent arrived at it. Notebooks provide four critical benefits:

Transparency: See the agent's thought process step-by-step
Reproducibility: Replay and refine workflows
Built-in Gating: Control agent reasoning at the source with validation checkpoints
Headless Simplicity: Serve as pure data structures via API/MCP tools without UI overhead

Architecture Pattern:

Unlike the Structured Journal pattern (which maintains state in the server), the Notebook pattern typically:

Uses a CLI application to serve the notebook to the model (headless - no UI needed)
Provides both markdown cells (guidance) and code cells (actions)
Allows non-linear execution (jump to cells, re-run, modify)
Maintains execution history and cell outputs
Can be persisted and shared as templates
Serves notebooks as data structures via MCP tools (agents interact via API, not visually)
Enables gating between cells (validation, checkpoints, required steps)

Notebook Structure:

interface NotebookCell {
  id: string;
  type: 'markdown' | 'code';
  content: string;
  output?: string;
  executionCount?: number;
  metadata?: Record<string, unknown>;
}

interface Notebook {
  cells: NotebookCell[];
  metadata: {
    language: string;
    title: string;
    description?: string;
  };
}

Tool Design:

notebook_create: Initialize new notebook with optional preset template
notebook_add_cell: Add markdown or code cells
notebook_run_cell: Execute a specific cell (can enforce gating rules)
notebook_get_cell: Retrieve cell content and output
notebook_validate_progression: Check if agent can proceed to next cell (gating)
notebook_export: Save notebook for sharing/reuse

Gating Example:

// Server can enforce that certain cells must be executed before others
// NOTE: Gates enforce STRUCTURE (has X been done?), not QUALITY (was X done well?)
async function runCell(cellId: string): Promise<Response> {
  const cell = notebook.getCell(cellId);
  const gates = notebook.getGatesForCell(cellId);
  
  // Check if prerequisites are met (structural validation only)
  for (const gate of gates) {
    if (!gate.isOpen()) {
      return {
        error: `Cannot execute cell ${cellId}: ${gate.requirement}`,
        suggestion: `Complete cells [${gate.requiredCells.join(', ')}] first`
      };
    }
  }
  
  // Execute cell if gates are open
  return executeCell(cell);
}

Use Cases:

Guided Workflows: Pre-filled code cells with markdown explanations as tutorials
Structured AI Behavior: Direct agents through logical flows
Notebook Presets: Pre-made templates for common tasks (Git workflows, database queries, API integrations)
Interactive Experimentation: Modify parameters and re-run to see impact

Implementation Reference:

Base platform: Srcbook
Advanced implementation: Clear Thought 1.5
Notebook format: EphemeralNotebook.ts example

Pattern Comparison: When to Use Which

Structured Journal vs. Notebook

Use Structured Journal when:

The process is primarily linear with optional branches
You want minimal overhead (single tool, simple state)
The focus is on the reasoning sequence itself
Human inspection is secondary (optional stderr logging)
The model drives the structure and pacing
Example: Sequential thinking, step-by-step analysis

Use Notebook when:

The process requires code execution and output inspection
Transparency and reproducibility are critical
You want to save/share the process as a template
Multiple passes and revisions are expected
Human inspection and modification are important
You need built-in validation gates between reasoning steps
Headless serving is preferred (agent interaction via API, no UI needed)
Example: Research workflows, debugging, tutorials, multi-stage validation processes

Hybrid Approach: You can combine both patterns - use a notebook where each cell represents a structured reasoning step that gets journaled.

Implementation Guide (TypeScript)

Project Setup

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from "@modelcontextprotocol/sdk/types.js";

Core Server Class Pattern

class EnhancementServer {
  private state: YourStateType = initialState;
  private config: ConfigType;

  constructor() {
    this.config = {
      disableLogging: (process.env.DISABLE_LOGGING || "").toLowerCase() === "true"
    };
  }

  private validateInput(input: unknown): ValidatedType {
    // Type-safe validation - throw clear errors for invalid input
  }

  public processRequest(input: unknown): {
    content: Array<{ type: string; text: string }>;
    structuredContent?: { [key: string]: unknown };
    isError?: boolean;
  } {
    try {
      const validated = this.validateInput(input);
      this.updateState(validated);
      
      if (!this.config.disableLogging) {
        this.logToStderr(validated);
      }
      
      const responseData = this.getResponseData(validated);
      
      return {
        content: [{ type: "text", text: JSON.stringify(responseData, null, 2) }],
        structuredContent: responseData,
        isError: false
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            status: 'failed'
          }, null, 2)
        }],
        isError: true
      };
    }
  }
}

Tool Definition Pattern

const ENHANCEMENT_TOOL: Tool = {
  name: "toolname",
  title: "Tool Display Name",  // Optional: display precedence: title > annotations.title > name
  
  description: `Comprehensive description that guides the model:
  
When to use this tool:
- Specific use cases

Key features:
- Feature explanations

Parameters explained:
- param1: What it means and how to use it

You should:
1. Step-by-step workflow guidance
2. Expected behavior patterns
3. When to stop/continue`,

  inputSchema: {
    type: "object",
    properties: {
      requiredField: { type: "string", description: "Clear description" },
      optionalField: { type: "boolean", description: "When to use this" }
    },
    required: ["requiredField"]
  },
  
  outputSchema: {  // Optional: enables structuredContent
    type: "object",
    properties: {
      status: { type: "string", description: "Operation status" },
      metadata: { type: "object", description: "Additional metadata" }
    },
    required: ["status"]
  },
  
  annotations: {  // Optional: hints about behavior
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false
  }
};

Server Initialization

const server = new Server(
  { name: "your-enhancement-server", version: "0.1.0" },
  { capabilities: { tools: {} } }
);

const enhancementServer = new EnhancementServer();

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [ENHANCEMENT_TOOL],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "toolname") {
    return enhancementServer.processRequest(request.params.arguments);
  }
  return {
    content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
    isError: true
  };
});

async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Enhancement Server running on stdio");
}

runServer().catch((error) => {
  console.error("Fatal error running server:", error);
  process.exit(1);
});

Best Practices

Tool Description Writing:

Front-load the "when to use" guidance
Explain parameters in context, not just technically
Provide workflow steps as numbered guidance
Be explicit about flexibility and adaptation

State Management:

Keep state minimal but sufficient for context
Validate all inputs before updating state
Return metadata that helps the model understand progress

Error Handling:

Validate input with clear, specific error messages
Guide the model toward correct usage in errors
Always return structured responses, even for errors
CRITICAL: Only validate format and structure, never evaluate reasoning quality

Human Output (optional):

Log to stderr, never stdout (stdout is for MCP protocol)
Make it visually distinct and informative
Make it toggleable via environment variables

Future Directions and Use Cases

As agentic networking matures, model enhancement servers enable novel patterns:

Long-Running Async Processes

Model enhancement servers provide Day One mechanisms for maintaining context across extended operations:

Batch jobs: Track progress through multi-hour processing tasks
Extended research: Maintain context during deep exploration (e.g., Exa's Websets running 30+ minutes)
Multi-stage workflows: Coordinate phases of complex work over hours or days

Multi-Client Coordination

Model enhancement servers can connect to multiple clients simultaneously, acting as a bulletin board where different clients post and retrieve information. This enables coordination between clients that have no other means of communication. MCP servers as proxies between clients may become the dominant use case per-server.

Formalized Workflows

Enhancement servers can support highly structured methodologies with clear definitions:

Scientific method: Hypothesis generation, experimentation, validation
Design thinking: Empathy, definition, ideation, prototyping, testing
Six Sigma: DMAIC (Define, Measure, Analyze, Improve, Control)

The server guides adherence to the methodology while allowing flexibility within steps.

Example Servers

Sequential Thinking Server

See example-servers/sequential-thinking for full working example.

What It Does: Guides models through step-by-step reasoning, supports revision, branching, and dynamic scope adjustment.

Key Design Decisions:

Single sequentialthinking tool handles entire workflow
Rich description (~50 lines of guidance)
Flexible schema (required fields for core, optional for advanced)
Dual output (JSON for model, formatted boxes for humans)
State tracking (linear history + branch dictionary)

The Whiteboard Analogy: Each time Claude calls sequentialthinking, imagine Claude as a student: works out a step on a whiteboard, walks away to reflect, returns when ready for the next step. The server provides the persistent whiteboard; the model provides the reasoning.

Structured Argumentation Server

See example-servers/structured-argumentation for full working example.

What It Does: Facilitates dialectical reasoning through formal argument structures (thesis → antithesis → synthesis).

Key Features: Formal claim/premises/conclusion structure, five argument types, relationship tracking, methodology guidance based on formal dialectical structure, auto-ID generation, confidence tracking.

Analogical Reasoning Server

See example-servers/analogical-reasoning for full working example.

What It Does: Supports systematic analogical reasoning with source/target domain mapping and element typing.

Key Features: Complex nested structures, element typing (entity/attribute/relation/process), mapping strength ratings, domain registry for reuse, inference tracking with confidence levels.

model-enhancement-servers