keep_thinking
Reason across multiple tool calls—without losing the thread or repeating dead ends.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents iterative structured reasoning through keep_thinking—hypothesis tracking, loop detection, risk gates, and session checkpoints—with nine other built-in tools and one API key.
When to use
- Debugging after two or more failed attempts—you need a written trail of what was tried.
- High-blast-radius work: auth, billing, schema migrations, multi-file refactors, production deploys.
- Ambiguous requirements—surface assumptions before editing.
- Long investigations where chat history loses hypotheses and conclusions.
When not to use
- You already know the fix—implement it.
- Single-step tasks: rename, typo, one known file (use read_code).
- Calling again with no new evidence— that is a loop; stop or change approach.
- Session already closed (previous call set nextThoughtNeeded: false).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| thought | string | Yes | Reasoning content (20–2000 chars). |
| thoughtNumber | integer | Yes | 1-based index in session. |
| totalThoughts | integer | Yes | Estimated total thoughts. |
| nextThoughtNeeded | boolean | Yes | false closes session + checkpoint. |
| confidence | number | Yes | 0–1; <0.5 forces revision. |
| thoughtType | enum | Yes | hypothesis | observation | plan | revision | conclusion | question | debug |
| goalAnchor | string | No* | Required after thought 2 (two-strike rule). |
| sessionId | uuid | No | Resume session; injects prior checkpoint. |
| actionReady | boolean | No | Planning complete—minimal response. |
| lastActions | string[] | No | Last 2–5 tool calls (max 5). |
| toolOutputRelevance | enum | No | critical | supporting | noise | error |
| assumptions | array | No | Max 5; mark invalidated when wrong. |
| revises | integer | No | Thought number this revision corrects. |
Limits: Does not run code or edit files. Sessions expire (idle ~30 min, completed ~1 hr in memory). Requires authenticated user for checkpoints. Not a substitute for check_test or explain_architecture.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex API key and hosted MCP in your editor.
- Meaningful **thought** text—include file names, errors, and concrete hypotheses.
- After thought 2, include **goalAnchor** (one sentence restating the task) or the server blocks on the second miss.
- Pass **lastActions** (last 2–5 tool calls) so boredom detection can fire.
Token and request cost
Each keep_thinking call is typically a few hundred tokens in and out. The value is avoiding repeated read_code/find_code cycles that cost thousands of tokens when the agent forgets what failed. Free tier: 555 requests/month total across all ten tools.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "keep_thinking", "arguments": { "thought": "Checkout 500s started after v4.2. Log points to stripe-handler.ts:47 — amount undefined. Hypothesis: webhook payload shape changed after Stripe API version bump.", "thoughtNumber": 1, "totalThoughts": 4, "nextThoughtNeeded": true, "confidence": 0.45, "thoughtType": "hypothesis", "lastActions": ["get_project_context", "find_code stripe-handler"] } }}Response shape
Response shape
{ "thoughtConfirmed": "Hypothesis recorded…", "shouldContinue": true, "riskLevel": "none", "forceRevision": false, "recommendedTool": { "name": "read_code", "confidence": 0.85, "rationale": "Verify handler implementation" }, "repetitionWarning": null, "boredLoopDetected": false, "approachingLimit": false, "checkpointWritten": false}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Multi-step debug / plan | keep_thinking | read_code alone |
| Read implementation | read_code | keep_thinking |
| Which files to open | check_test | keep_thinking |
| Map auth → API → DB flow | explain_architecture | keep_thinking |
What it can do in your codebase
- Record hypothesis, observation, plan, revision, conclusion, question, debug thoughts
- riskLevel blocks critical/high-risk plans (drop table, rm -rf, force push to prod, …)
- repetitionWarning when new thought is too similar to earlier ones
- boredLoopDetected when lastActions repeats the same tool call twice
- endless loop stop when 3+ of last 5 toolOutputRelevance are noise/error
- forceRevision when confidence < 0.5
- approachingLimit at thought 8 (2 calls left before hard cap)
- recommendedTool suggests next Zephex tool on plan/conclusion thoughts
- checkpointWritten on session end—resume with sessionId to inject rejected approaches
- reflectionPrompt with recovery questions when a loop is detected
- actionReady: true for a minimal response when planning is done
Common response fields
Why teams use it
Multi-call by design
One thought per MCP call. The agent builds reasoning over several calls, not one giant hidden chain-of-thought block.
Stops dangerous plans
Destructive or production-risk language in a thought can set shouldContinue: false before any code runs.
Pairs with code tools
recommendedTool points to find_code, read_code, check_test, etc.—thinking first, then evidence.
Does not edit code
Planning and investigation only. Implementation still uses read_code and your editor.
Output fields to act on
| Field | Meaning |
|---|---|
| shouldContinue | false = stop reasoning (risk, loop, or session ended). |
| riskLevel | critical/high can block continuation on dangerous plans. |
| forceRevision | true when confidence < 0.5—revise before proceeding. |
| checkpointWritten | true when session closed; summary stored for resume. |
| recommendedTool | Suggested next Zephex tool with short rationale. |
| toolOutputRelevance | critical | supporting | noise | error — feeds loop detection. |
thoughtType values
How it fits your workflow
- Thought 1 — hypothesis or question; optional sessionId to resume prior checkpoint.
- Thoughts 2+ — include goalAnchor; pass toolOutputRelevance after each tool call.
- Use lastActions so boredom detection sees repeated reads.
- When ready to code: actionReady true or nextThoughtNeeded false with conclusion.
- Then read_code / find_code only on evidence from the session—not random files.
Troubleshooting
- goalAnchor missing → required after thought 2; restate the original task in one sentence.
- Session complete → start fresh (omit sessionId) or use a new UUID sessionId.
- shouldContinue: false with riskLevel critical → thought proposed drop table / rm -rf / prod deploy—get human approval.
- boredLoopDetected: true → last two lastActions identical; stop re-reading the same file.
- repetitionWarning → you are restating the same hypothesis; revise or gather new evidence.
How to verify it works
- Connect Zephex MCP; confirm keep_thinking in tools/list.
- Send one hypothesis thought with thoughtNumber 1; confirm shouldContinue: true and a sessionId in the response (or pass your own UUID).
- Send thought 3 with goalAnchor set and nextThoughtNeeded: false; confirm checkpointWritten: true.
Common questions
Billing and plan limits: FAQ, usage limits.
How is keep_thinking different from extended thinking or a single think tool?
keep_thinking is an explicit multi-call MCP tool: you send structured thoughts across turns, get loop and risk signals, and can checkpoint to Supabase. It does not replace read_code or find_code for evidence—it organizes when to call them.
Which MCP tool should I use for a complex debugging session?
Start with get_project_context or explain_architecture if the system is unfamiliar, then keep_thinking to log hypotheses as you go. Use find_code and read_code for evidence. Pass findings via toolOutputRelevance and lastActions so loops are caught early.
How do I use keep_thinking with Cursor?
With Zephex in .cursor/mcp.json, ask the agent to record each major hypothesis via keep_thinking before more file reads. Require goalAnchor after the second thought. End with nextThoughtNeeded false before proposing code changes.
What happens at 10 thoughts?
The server enforces MAX_CALLS_PER_SESSION = 10. approachingLimit warns at thought 8. When the cap hits or you set nextThoughtNeeded false, the session completes and checkpointWritten should be true.
Why was I blocked for missing goalAnchor?
After thought 2, goalAnchor is required to prevent drift. One miss sets goalAnchorMissing; two consecutive misses throw an error until you restate the task in goalAnchor.
Need test health first? check_test returns health and broken_areas; keep_thinking tracks what you learn in them.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
check_test picks files; keep_thinking tracks reasoning across calls—use check_test first for file lists, then check_test.
For AI agents (JSON)
{"tool":"keep_thinking","pattern":"one thought per call","end":"nextThoughtNeeded false","then":"read_code"}