diff --git a/docs/customize/deep-dives/mcp.mdx b/docs/customize/deep-dives/mcp.mdx
index 2ad80571159..d6846f927e9 100644
--- a/docs/customize/deep-dives/mcp.mdx
+++ b/docs/customize/deep-dives/mcp.mdx
@@ -25,6 +25,12 @@ explore available MCP servers
MCP can only be used in the **agent** mode.
+### Model Compatibility
+
+When using MCP with Ollama models, Continue automatically handles model-specific message formatting requirements. For example, Mistral/Ministral models require system messages before tool interactions, and Gemma3 models reject certain tool_call fields. Continue normalizes these messages automatically—no configuration needed.
+
+For details on verified working models and troubleshooting, see [Ollama MCP tool calling issues](/troubleshooting#ollama-mcp-tool-calling-issues).
+
## Quick Start: How to Set Up Your First MCP Server
Below is a quick example of setting up a new MCP server for use in your config:
diff --git a/docs/guides/ollama-guide.mdx b/docs/guides/ollama-guide.mdx
index 200ebbdf319..df214892cb5 100644
--- a/docs/guides/ollama-guide.mdx
+++ b/docs/guides/ollama-guide.mdx
@@ -199,6 +199,24 @@ models:
See the [Model Capabilities guide](/customize/deep-dives/model-capabilities) for more details.
+#### MCP Tool Calling Compatibility
+
+When using Ollama models with [MCP (Model Context Protocol)](/customize/deep-dives/mcp) in agent mode, Continue automatically handles model-specific message formatting requirements:
+
+
+ **Automatic Fix**: Continue includes message normalization that runs automatically for Mistral, Ministral, and Gemma models when using MCP tool calling. No configuration needed.
+
+
+**Mistral/Ministral models** require system messages before tool interactions:
+- Continue automatically reorders messages to comply with this requirement
+- Fixes: `400 Bad Request: Unexpected role 'system' after role 'tool'` error
+
+**Gemma3 models** reject tool_calls with an `index` field:
+- Continue automatically removes the `index` field for Gemma models
+- Fixes: `400 Bad Request: Invalid 'tool_calls': unknown variant 'index'` error
+
+For more details about MCP tool calling issues and verified working models, see [Ollama MCP troubleshooting](/troubleshooting#ollama-mcp-tool-calling-issues).
+
### How to Configure Advanced Settings
For optimal performance, consider these advanced configuration options:
@@ -307,7 +325,9 @@ ollama pull deepseek-r1:32b
1. Add `capabilities: [tool_use]` to your model config
2. If still not working, the model may not actually support tools
-3. Switch to a model with confirmed tool support (Llama 3.1, Mistral)
+3. Switch to a model with confirmed tool support (Llama 3.1, Mistral, DeepSeek V3.1, Qwen3)
+
+For MCP tool calling, see [verified working models](/troubleshooting#ollama-mcp-tool-calling-issues) that have been tested with Continue.
#### Using Hub Blocks in Local Config
diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
index 4e2bc9fd3d4..3493ae712e2 100644
--- a/docs/troubleshooting.mdx
+++ b/docs/troubleshooting.mdx
@@ -8,7 +8,8 @@ description: "Comprehensive guide to resolving common issues with Continue, incl
3. [Download an older version](#download-an-older-version)
4. [Resolve keyboard shortcut issues](#keyboard-shortcuts-not-resolving)
5. [MCP Server connection issues](#mcp-server-connection-issues)
-6. [Check FAQs for common issues](/faqs)
+6. [Ollama MCP tool calling issues](#ollama-mcp-tool-calling-issues)
+7. [Check FAQs for common issues](/faqs)
## Check the logs
@@ -104,6 +105,60 @@ To find the full path to a command on your system:
This issue typically affects macOS users with large development environments and is being tracked in [#7870](https://github.com/continuedev/continue/issues/7870) and [#6699](https://github.com/continuedev/continue/issues/6699).
+## Ollama MCP tool calling issues
+
+When using Ollama models with MCP tool calling in agent mode, certain models may experience compatibility issues due to message formatting requirements. Continue automatically handles these cases with message normalization.
+
+### Mistral and Ministral models
+
+
+ **Error**: `400 Bad Request: Unexpected role 'system' after role 'tool'`
+
+
+Mistral family models (including Mistral Large 3 and Ministral 3) require system messages to appear before any tool interactions. Continue automatically reorders system messages when detected:
+
+- System messages appearing after tool messages are converted to user messages
+- System messages before tool interactions are preserved
+
+**No action required** - this is handled automatically by Continue's message normalization.
+
+### Gemma3 models
+
+
+ **Error**: `400 Bad Request: Invalid 'tool_calls': unknown variant 'index'`
+
+
+Gemma3 models (e.g., Gemma3 27B) reject tool_calls containing an `index` field. Continue automatically removes this field for Gemma models.
+
+**Note**: If you're still experiencing issues with Gemma models, the `index` field may be added at a different point in the processing pipeline. In this case, try using an alternative model that's confirmed to work with MCP tool calling.
+
+### Verified working models
+
+The following Ollama models have been tested and confirmed to work with MCP tool calling:
+
+
+
+ - DeepSeek V3.1 (671B Cloud)
+ - Qwen3 Coder (480B Cloud)
+ - Qwen3 VL (235B Cloud)
+ - Qwen3 Next (80B Cloud)
+ - Cogito 2.1 (671B Cloud)
+ - GLM 4.6 (Cloud)
+ - Minimax M2 (Cloud)
+ - Kimi K2 (1T Cloud)
+ - Mistral Large 3 (675B Cloud)*
+ - Ministral 3*
+
+ *Fixed by message normalization
+
+
+
+### Related issues
+
+For more information about model-specific compatibility and MCP tool calling:
+- [MCP Configuration Guide](/customize/deep-dives/mcp)
+- [Ollama Setup Guide](/guides/ollama-guide)
+- [Model Capabilities](/customize/deep-dives/model-capabilities)
## Still having trouble?