Smithery is now a part of Arcade.dev! Read more in our announcement here
Guide for creating MCP servers that enhance LLM reasoning through structured processes, persistence, and workflow guidance...
Based on MCP Protocol Version: 2025-06-18
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 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.
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.
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.
The most important thing to understand about model enhancement servers:
Model enhancement servers are scaffolding, not reasoning engines. They are persistence mechanisms and workflow guides, not AI models themselves.
What the server does:
What the server does NOT do:
The value of model enhancement comes from:
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.
Purpose: Track and persist a sequence of reasoning steps while guiding the model through a cognitive process.
Key Features:
When to Use:
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:
sequentialthinking)Variations: The Structured Journal pattern can be specialized for specific methodologies:
Novel Strategies:
Purpose: Provide a Jupyter-like notebook interface where models work through problems with full transparency and reproducibility.
Key Features:
When to Use:
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:
Architecture Pattern:
Unlike the Structured Journal pattern (which maintains state in the server), the Notebook pattern typically:
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 templatenotebook_add_cell: Add markdown or code cellsnotebook_run_cell: Execute a specific cell (can enforce gating rules)notebook_get_cell: Retrieve cell content and outputnotebook_validate_progression: Check if agent can proceed to next cell (gating)notebook_export: Save notebook for sharing/reuseGating 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:
Implementation Reference:
Use Structured Journal when:
Use Notebook when:
Hybrid Approach: You can combine both patterns - use a notebook where each cell represents a structured reasoning step that gets journaled.
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";
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
};
}
}
}
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
}
};
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);
});
Tool Description Writing:
State Management:
Error Handling:
Human Output (optional):
As agentic networking matures, model enhancement servers enable novel patterns:
Model enhancement servers provide Day One mechanisms for maintaining context across extended operations:
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.
Enhancement servers can support highly structured methodologies with clear definitions:
The server guides adherence to the methodology while allowing flexibility within steps.
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:
sequentialthinking tool handles entire workflowThe 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.
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.
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.
