Building a Sequential‑Thinking MCP Server with Spring AI 1.0 – Step‑by‑Step Guide

Sequential Thinking MCP Server

Sequential Thinking MCP Server is an MCP‑provided server that structures problem solving into ordered, reflective steps. It decomposes complex tasks into manageable steps, allows revision, supports branching, and can dynamically adjust the total number of steps.

Key Features

Decompose problems into stepwise thoughts

Iteratively refine understanding

Branch to alternative reasoning paths

Adjust total thought count on the fly

Generate and verify solution hypotheses

Configuration

Enable the server in the MCP configuration file with the following JSON snippet:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

The server can run in STDIO mode or in HTTP SSE mode as demonstrated later.

Tool Description

A ToolConstant class holds the tool name and a detailed English description that explains when and how to use the tool.

public class ToolConstant {
    public static final String TOOL_NAME = "sequentialthinking";
    public static final String TOOL_DESC = "A detailed tool for dynamic and reflective problem‑solving through thoughts.
"
        + "It helps analyse problems with a flexible thinking process that can adapt and evolve.
"
        + "Each thought can build on, question, or revise previous insights as understanding deepens.
"
        + "When to use this tool: 
"
        + "- Breaking down complex problems into steps
"
        + "- Planning and design with room for revision
"
        + "- Analysis that might need course correction
"
        + "- Problems where the full scope is unclear at the start
"
        + "- Tasks requiring multi‑step solutions
"
        + "- Maintaining context across multiple steps
"
        + "- Filtering out noisy information
"
        + "Key features: 
"
        + "- Adjustable total thoughts
"
        + "- Ability to question or revise previous thoughts
"
        + "- Add thoughts after an apparent end
"
        + "- Express uncertainty and explore alternatives
"
        + "- Non‑linear thought flow (branching/backtracking)
"
        + "- Generate and verify solution hypotheses
"
        + "- Repeat until satisfied
"
        + "- Provide a final correct answer";
}

Data Model

The ThoughtData class captures a single thinking step:

@Data
public class ThoughtData {
    public String thought;
    public int thoughtNumber;
    public int totalThoughts;
    public boolean nextThoughtNeeded;
    public Boolean isRevision;
    public Integer revisesThought;
    public Integer branchFromThought;
    public String branchId;
    public Boolean needsMoreThoughts;
}

Core Processor

The SequentialThinkingServer class implements three main methods:

validateThoughtData(Object input) – validates the incoming map, converts it to a ThoughtData instance, and throws descriptive exceptions for type mismatches.

formatThought(ThoughtData thoughtData) – creates a pretty‑printed Unicode box that indicates whether the step is a normal thought, a revision, or a branch.

processThought(Object input) – validates the input, updates the thought history, records branches, prints the formatted box to System.err, and returns a map containing the current step number, total steps, continuation flag, branch list, and history length.

Sample formatted output:

┌─────────────────────────────────────┐
│ 💭 Thought 1/3                      │
├─────────────────────────────────────┤
│ 我们应该先理解用户的需求是什么。   │
└─────────────────────────────────────┘

Tool Service

The tool is exposed via a Spring @Service class that delegates to the processor:

@Service
public class SequentialThinkingServerToolService {
    SequentialThinkingServer sequentialThinkingServer = new SequentialThinkingServer();

    @Tool(name = ToolConstant.TOOL_NAME, description = ToolConstant.TOOL_DESC)
    public Map<String, Object> sequentialthinking(
            @ToolParam(description = "Your current thinking step") String thought,
            @ToolParam(description = "Whether another thought step is needed") Boolean nextThoughtNeeded,
            @ToolParam(description = "Current thought number") Integer thoughtNumber,
            @ToolParam(description = "Estimated total thoughts needed") Integer totalThought,
            @ToolParam(description = "Is this a revision?", required = false) Boolean isRevision,
            @ToolParam(description = "Which thought is being revised", required = false) Integer revisesThought,
            @ToolParam(description = "Branching point thought number", required = false) Integer branchFromThought,
            @ToolParam(description = "Branch identifier", required = false) String branchId,
            @ToolParam(description = "If more thoughts are needed", required = false) Boolean needsMoreThoughts) {
        Map<String, Object> inputMap = new HashMap<>();
        inputMap.put("thought", thought);
        inputMap.put("nextThoughtNeeded", nextThoughtNeeded);
        inputMap.put("thoughtNumber", thoughtNumber);
        inputMap.put("totalThoughts", totalThought);
        inputMap.put("isRevision", isRevision);
        inputMap.put("revisesThought", revisesThought);
        inputMap.put("branchFromThought", branchFromThought);
        inputMap.put("branchId", branchId);
        inputMap.put("needsMoreThoughts", needsMoreThoughts);
        return sequentialThinkingServer.processThought(inputMap);
    }
}

Spring Boot Application

Register the tool in the main application class:

@SpringBootApplication
public class ToolApplication {
    public static void main(String[] args) {
        SpringApplication.run(ToolApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider serverTools(SequentialThinkingServerToolService toolService) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(toolService)
                .build();
    }
}

Project Setup

Add Spring AI 1.0.0 and Spring Boot dependencies in pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>cn.aijavapro</groupId>
    <artifactId>sequentialthinking-sse-mcp-server</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.2</version>
    </parent>
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.0.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.83</version>
        </dependency>
    </dependencies>
</project>

Create application.yml to enable the server and define SSE endpoints:

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: sequentialthink-sse-mcp-server
        version: 1.0.0
        type: ASYNC  # recommended for reactive applications
        sse-endpoint: /sse
        sse-message-endpoint: /mcp/message

Running the Server

Build the project with Maven and start the Spring Boot application. The server listens on the SSE endpoint /sse and the MCP message endpoint /mcp/message. An MCP‑compatible client (e.g., Trae) can add the server URL, create an agent, and send a problem for processing.

Performance Considerations

Higher token consumption because each reasoning step is sent to the model.

Longer overall latency as the problem is decomposed and solved step‑by‑step.

Potential context‑window limits for very large task trees; consider splitting massive problems across multiple sessions.

Guidelines for optimal performance:

Define the required depth of analysis up front.

Scope especially complex domains narrowly.

Break extremely large problems into separate sequential‑thinking sessions.

Prompt Template

Typical prompt for invoking the sequential thinking method (English):

Please use the sequential thinking method to solve this problem: [problem description]
I'd like you to:
1. Define the problem clearly
2. Break it down into atomic sub‑tasks
3. Solve each sub‑task systematically
4. Integrate the results into a comprehensive solution

Chinese version:

请使用“顺序思维法”（Sequential Thinking Method）来解决以下问题：[问题描述]。
我希望你能做到：
1、清晰地定义问题
2、将问题拆解为最小的原子子任务
3、系统性地逐一解决每个子任务
4、将各个子任务的结果整合为一个完整的解决方案

References

Official sequential‑thinking guide: https://www.ontariomcp.ca/sequential-thinking-mcp

Reference implementation repository: https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking