Merge pull request #6323 from menloresearch/rp/docs-v0.6.9

docs: Major restructure and consolidation

docs/src/pages/_meta.json

@@ -7,9 +7,10 @@
       "layout": "raw"
     }
   },
-  "docs": {
+  "Documentation": {
     "type": "page",
-    "title": "Documentation"
+    "title": "Documentation",
+    "href": "https://docs.jan.ai"
   },
   "platforms": {
     "type": "page",

docs/src/pages/changelog/2025-08-28-image-support.mdx

@@ -0,0 +1,106 @@
+---
+title: "Jan v0.6.9: Image support, stable MCP, and powerful model tools"
+version: 0.6.9
+description: "Major multimodal support with image uploads, MCP out of experimental, auto-detect model capabilities, and enhanced tool calling"
+date: 2025-08-28
+ogImage: "/assets/images/changelog/jan-images.gif"
+---
+
+import ChangelogHeader from "@/components/Changelog/ChangelogHeader"
+import { Callout } from 'nextra/components'
+
+<ChangelogHeader title="Jan v0.6.9: Image support, stable MCP, and powerful model tools" date="2025-08-28" ogImage="/assets/images/changelog/jan-images.gif" />
+
+## Highlights 🎉
+
+v0.6.9 delivers two highly requested features: **image support for multimodal models** and **stable MCP** (no more experimental flags!). Plus intelligent model capability detection, enhanced tool calling, and major UX improvements.
+
+### 🖼️ Multimodal AI is here
+
+**Image upload support** — Finally! Upload images directly in your chats and get visual understanding from compatible models:
+- **Local models**: Automatic support for Gemma3, Qwen3, and other vision-capable models
+- **Cloud models**: Manual toggle for GPT-4V, Claude 3.5 Sonnet, Gemini Pro Vision
+- **Smart detection**: Jan automatically identifies which models support images
+- **Privacy first**: Local models process images entirely offline
+
+The team has been working hard to bring this long-awaited capability to Jan, and it's been worth the wait.
+
+### 🔧 MCP is stable
+
+**Model Context Protocol** graduated from experimental to stable:
+- **No more experimental flags** — MCP tools work out of the box
+- **Better error handling** for smoother MCP server connections
+- **Cancel tool calls** mid-execution when needed
+- **Enhanced reliability** with improved server status tracking
+
+MCP unlocks powerful workflows: web search, code execution, productivity integrations, and more.
+
+### 🎯 Intelligent model management
+
+- **Auto-detect capabilities**: Jan identifies tool calling and vision support for local models
+- **Model compatibility checker**: Hub shows hardware requirements before download
+- **Favorite models**: Mark frequently used models for quick access
+- **Universal GGUF import**: Import any valid .gguf file regardless of extension
+- **Hardware-aware suggestions**: Get model recommendations based on your system specs
+
+### 🚀 Enhanced tool calling
+
+- **GPT-OSS models**: Upgraded llama.cpp brings tool calling to more open-source models
+- **Improved performance**: Better tool execution with upgraded engine
+- **Remote provider control**: Manual toggle for cloud model capabilities
+- **Streamlined workflows**: Cancel operations, better error handling
+
+## Major Features
+
+### 🖼️ Multimodal support
+- **Image uploads** work with compatible local and cloud models
+- **Automatic detection** for local model vision capabilities
+- **Manual toggle** for remote providers (GPT-4V, Claude, Gemini)
+- **Privacy-preserving** local image processing
+
+### 🔧 Stable MCP
+- **MCP Server stable release** — no more experimental flags needed
+- **Enhanced error handling** for MCP connections
+- **Tool cancellation** support during execution
+- **Improved server status** synchronization
+
+### 🎯 Smart model features
+- **Favorite models** — bookmark your go-to models
+- **Auto-capability detection** for local models
+- **Hardware compatibility** checks in Hub
+- **Universal GGUF import** regardless of file extension
+
+### ⚡ Enhanced engine
+- **Tool calling support** for GPT-OSS models
+- **Upgraded llama.cpp** version with stability improvements
+- **Better performance** across model types
+
+## Improvements
+
+### 🔄 API & automation
+- **Auto-start API server** on Jan startup (optional)
+- **Model auto-loading** when API server starts
+- **Ollama endpoint** support restored for custom configurations
+
+### 🎨 User experience
+- **Thinking windows** for OpenRouter models render correctly
+- **Better error messages** across MCP operations
+- **Improved import UX** with retired model cleanup
+- **CPU architecture** detection at runtime
+
+### 🔧 Technical enhancements
+- **Vulkan backend** re-enabled for integrated GPUs with sufficient memory
+- **Enhanced stability** with better error handling
+- **Performance optimizations** across the board
+
+## Thanks to our incredible team
+
+The engineering team delivered major features that users have been requesting for months. Image support required deep multimodal AI integration, while stabilizing MCP involved extensive testing and refinement. The auto-detection features showcase thoughtful UX design that makes AI more accessible.
+
+Special recognition to the contributors who made v0.6.9 possible through their dedication to bringing powerful, privacy-focused AI capabilities to everyone.
+
+---
+
+Update your Jan or [download the latest](https://jan.ai/).
+
+For the complete list of changes, see the [GitHub release notes](https://github.com/janhq/jan/releases/tag/v0.6.9).

website/astro.config.mjs

@@ -14,7 +14,7 @@ const __dirname = dirname(__filename)
 // https://astro.build/config
 export default defineConfig({
   // Deploy to the new v2 subdomain
-  site: 'https://v2.jan.ai',
+  site: 'https://docs.jan.ai',
   integrations: [
     mermaid({
       theme: 'default',
@@ -40,127 +40,216 @@ export default defineConfig({
             icon: 'rocket',
             items: [
               {
-                label: 'GETTING STARTED',
+                label: '🚀 QUICK START',
                 items: [
-                  { label: 'QuickStart', slug: 'jan/quickstart' },
+                  { label: 'Getting Started', slug: 'jan/quickstart' },
                   {
-                    label: 'Install 👋 Jan',
+                    label: 'Install Jan',
                     collapsed: false,
                     autogenerate: { directory: 'jan/installation' },
                   },
+                  { label: 'AI Assistants', slug: 'jan/assistants' },
+                ],
+              },
+              {
+                label: '🤖 MODELS',
+                items: [
+                  { label: 'Overview', slug: 'jan/manage-models' },
                   {
-                    label: 'Models',
-                    collapsed: true,
-                    autogenerate: { directory: 'jan/jan-models' },
+                    label: 'Jan Models',
+                    collapsed: false,
+                    items: [
+                      {
+                        label: 'Jan v1',
+                        slug: 'jan/jan-models/jan-v1',
+                      },
+                      {
+                        label: 'Research Models',
+                        collapsed: true,
+                        items: [
+                          {
+                            label: 'Jan Nano 32k',
+                            slug: 'jan/jan-models/jan-nano-32',
+                          },
+                          {
+                            label: 'Jan Nano 128k',
+                            slug: 'jan/jan-models/jan-nano-128',
+                          },
+                          {
+                            label: 'Lucy',
+                            slug: 'jan/jan-models/lucy',
+                          },
+                        ],
+                      },
+                    ],
                   },
-                  { label: 'Assistants', slug: 'jan/assistants' },
                   {
                     label: 'Cloud Providers',
                     collapsed: true,
                     items: [
+                      { label: 'OpenAI', slug: 'jan/remote-models/openai' },
                       {
                         label: 'Anthropic',
                         slug: 'jan/remote-models/anthropic',
                       },
-                      { label: 'OpenAI', slug: 'jan/remote-models/openai' },
                       { label: 'Gemini', slug: 'jan/remote-models/google' },
-                      {
-                        label: 'OpenRouter',
-                        slug: 'jan/remote-models/openrouter',
-                      },
-                      { label: 'Cohere', slug: 'jan/remote-models/cohere' },
+                      { label: 'Groq', slug: 'jan/remote-models/groq' },
                       {
                         label: 'Mistral',
                         slug: 'jan/remote-models/mistralai',
                       },
-                      { label: 'Groq', slug: 'jan/remote-models/groq' },
+                      { label: 'Cohere', slug: 'jan/remote-models/cohere' },
+                      {
+                        label: 'OpenRouter',
+                        slug: 'jan/remote-models/openrouter',
+                      },
+                      {
+                        label: 'HuggingFace 🤗',
+                        slug: 'jan/remote-models/huggingface',
+                      },
                     ],
                   },
                   {
-                    label: 'Tutorials',
+                    label: 'Custom Providers',
+                    slug: 'jan/custom-provider',
+                  },
+                  {
+                    label: 'Multi-Modal Models',
+                    slug: 'jan/multi-modal',
+                  },
+                ],
+              },
+              {
+                label: '🔧 TOOLS & INTEGRATIONS',
+                items: [
+                  { label: 'What is MCP?', slug: 'jan/mcp' },
+                  {
+                    label: 'Examples & Tutorials',
                     collapsed: true,
                     items: [
                       {
-                        label: 'Browser Control',
-                        slug: 'jan/mcp-examples/browser/browserbase',
+                        label: 'Web & Search',
+                        collapsed: true,
+                        items: [
+                          {
+                            label: 'Browser Control',
+                            slug: 'jan/mcp-examples/browser/browserbase',
+                          },
+                          {
+                            label: 'Serper Search',
+                            slug: 'jan/mcp-examples/search/serper',
+                          },
+                          {
+                            label: 'Exa Search',
+                            slug: 'jan/mcp-examples/search/exa',
+                          },
+                        ],
                       },
                       {
-                        label: 'Code Sandbox (E2B)',
-                        slug: 'jan/mcp-examples/data-analysis/e2b',
+                        label: 'Data & Analysis',
+                        collapsed: true,
+                        items: [
+                          {
+                            label: 'Jupyter Notebooks',
+                            slug: 'jan/mcp-examples/data-analysis/jupyter',
+                          },
+                          {
+                            label: 'Code Sandbox (E2B)',
+                            slug: 'jan/mcp-examples/data-analysis/e2b',
+                          },
+                          {
+                            label: 'Deep Financial Research',
+                            slug: 'jan/mcp-examples/deepresearch/octagon',
+                          },
+                        ],
                       },
                       {
-                        label: 'Jupyter Notebooks',
-                        slug: 'jan/mcp-examples/data-analysis/jupyter',
+                        label: 'Productivity',
+                        collapsed: true,
+                        items: [
+                          {
+                            label: 'Linear',
+                            slug: 'jan/mcp-examples/productivity/linear',
+                          },
+                          {
+                            label: 'Todoist',
+                            slug: 'jan/mcp-examples/productivity/todoist',
+                          },
+                        ],
                       },
                       {
-                        label: 'Design with Canva',
-                        slug: 'jan/mcp-examples/design/canva',
-                      },
-                      {
-                        label: 'Deep Financial Research',
-                        slug: 'jan/mcp-examples/deepresearch/octagon',
-                      },
-                      {
-                        label: 'Serper Search',
-                        slug: 'jan/mcp-examples/search/serper',
-                      },
-                      {
-                        label: 'Exa Search',
-                        slug: 'jan/mcp-examples/search/exa',
-                      },
-                      {
-                        label: 'Linear',
-                        slug: 'jan/mcp-examples/productivity/linear',
-                      },
-                      {
-                        label: 'Todoist',
-                        slug: 'jan/mcp-examples/productivity/todoist',
+                        label: 'Creative',
+                        collapsed: true,
+                        items: [
+                          {
+                            label: 'Design with Canva',
+                            slug: 'jan/mcp-examples/design/canva',
+                          },
+                        ],
                       },
                     ],
                   },
                 ],
               },
               {
-                label: 'EXPLANATION',
+                label: '⚙️ DEVELOPER',
                 items: [
                   {
-                    label: 'Local AI Engine',
-                    slug: 'jan/explanation/llama-cpp',
+                    label: 'Local API Server',
+                    collapsed: false,
+                    items: [
+                      { label: 'Overview', slug: 'local-server' },
+                      {
+                        label: 'API Configuration',
+                        slug: 'local-server/api-server',
+                      },
+                      {
+                        label: 'Engine Settings',
+                        slug: 'local-server/llama-cpp',
+                      },
+                      {
+                        label: 'Server Settings',
+                        slug: 'local-server/settings',
+                      },
+                      {
+                        label: 'Integrations',
+                        collapsed: true,
+                        autogenerate: {
+                          directory: 'local-server/integrations',
+                        },
+                      },
+                    ],
                   },
                   {
-                    label: 'Model Parameters',
-                    slug: 'jan/explanation/model-parameters',
-                  },
-                ],
-              },
-              {
-                label: 'ADVANCED',
-                items: [
-                  { label: 'Manage Models', slug: 'jan/manage-models' },
-                  { label: 'Model Context Protocol', slug: 'jan/mcp' },
-                ],
-              },
-              {
-                label: 'Local Server',
-                items: [
-                  {
-                    label: 'All',
+                    label: 'Technical Details',
                     collapsed: true,
-                    autogenerate: { directory: 'local-server' },
+                    items: [
+                      {
+                        label: 'Model Parameters',
+                        slug: 'jan/explanation/model-parameters',
+                      },
+                    ],
                   },
                 ],
               },
               {
-                label: 'REFERENCE',
+                label: '📚 REFERENCE',
                 items: [
                   { label: 'Settings', slug: 'jan/settings' },
-                  { label: 'Jan Data Folder', slug: 'jan/data-folder' },
+                  { label: 'Data Folder', slug: 'jan/data-folder' },
                   { label: 'Troubleshooting', slug: 'jan/troubleshooting' },
                   { label: 'Privacy Policy', slug: 'jan/privacy' },
                 ],
               },
             ],
           },
+          {
+            label: 'Browser Extension',
+            link: '/browser/',
+            badge: { text: 'Alpha', variant: 'tip' },
+            icon: 'puzzle',
+            items: [{ label: 'Overview', slug: 'browser' }],
+          },
           {
             label: 'Jan Mobile',
             link: '/mobile/',

website/src/content/docs/browser/index.mdx

@@ -0,0 +1,41 @@
+---
+title: Jan Browser Extension
+description: Bring your favorite AI models to any website with Jan's browser extension.
+keywords:
+  [
+    Jan Browser Extension,
+    Jan AI,
+    Browser AI,
+    Chrome extension,
+    Firefox addon,
+    local AI,
+    ChatGPT alternative
+  ]
+banner:
+  content: 'Coming in September 2025. Currently testing it with selected users and internally. 🤓'
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+
+![Jan Browser Extension](/gifs/extension.png)
+
+## Your AI Models, Anywhere on the Web
+
+The Jan Browser Extension brings AI assistance directly to your browsing experience.
+Connect to your local Jan installation or any remote AI provider to get contextual help
+on any website without switching tabs.
+
+<Aside type="note">
+**Jan Browser Extension is not yet available.** We are working hard to bring you seamless
+AI integration across all your web browsing.
+</Aside>
+
+Access your preferred models without leaving your current page. Whether you're using local
+Jan models or remote providers, get instant AI assistance while reading, writing, or researching
+online.
+
+### Core Features Planned:
+- **Universal Access**: Use any Jan-compatible model from any website
+- **Context Integration**: Highlight text and get AI assistance instantly
+- **Privacy Options**: Choose between local processing or remote providers
+- **Seamless Experience**: No tab switching or workflow interruption required

website/src/content/docs/index.mdx

@@ -17,11 +17,13 @@ keywords:
     large language model,
     LLM,
   ]
+banner:
+  content: |
+    We just launched something cool! 👋Jan now <a href="./jan/multi-modal">supports image 🖼️ attachments</a> 🎉
 ---
 
 import { Aside } from '@astrojs/starlight/components';
 
-# Jan
 
 ![Jan's Cover Image](../../assets/jan_loaded.png)
 

website/src/content/docs/jan/custom-provider.mdx

@@ -0,0 +1,288 @@
+---
+title: Custom Providers
+description: Connect Jan to any OpenAI-compatible AI service, from major cloud providers to local inference servers.
+keywords:
+  [
+    Jan,
+    custom providers,
+    OpenAI API,
+    Together AI,
+    vLLM,
+    LMStudio,
+    transformers,
+    SGLang,
+    API integration,
+    local AI,
+    cloud AI,
+  ]
+sidebar:
+  badge:
+    text: New
+    variant: tip
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Jan's custom provider system lets you connect to any OpenAI-compatible API service. Whether you're using cloud providers like Together AI, Fireworks, or Replicate, or running local inference servers like vLLM, LMStudio, or transformers, Jan can integrate with them seamlessly.
+
+## What You Can Connect
+
+**Cloud Providers:**
+- Together AI, Fireworks, Replicate
+- Perplexity, DeepInfra, Anyscale
+- Any OpenAI-compatible API service
+
+**Local Inference Servers:**
+- vLLM, LMStudio, Ollama
+- SGLang, transformers, text-generation-webui
+- TensorRT-LLM, LocalAI
+
+**Self-Hosted Solutions:**
+- Your own API deployments
+- Enterprise AI gateways
+- Custom model endpoints
+
+## Setup Process
+
+### Add a New Provider
+
+Navigate to **Settings > Model Providers** and click **Add Provider**.
+
+![Add custom provider button](../../../assets/customprovider.png)
+
+Enter a name for your provider. We'll use Together AI as our example.
+
+![Provider name modal](../../../assets/customprovider2.png)
+
+### Get Your API Credentials
+
+For cloud providers, you'll need an account and API key. Here's Together AI's dashboard showing your credits and API key location.
+
+![Together AI dashboard](../../../assets/customprovider3.png)
+
+<Aside type="caution">
+Keep your API keys secure and never share them publicly. Most providers charge based on usage, so monitor your credits and spending.
+</Aside>
+
+### Configure the Provider
+
+Back in Jan, fill in your provider's details:
+
+**API Base URL:** The endpoint for your service (e.g., `https://api.together.xyz/`)
+**API Key:** Your authentication token
+
+![Provider configuration](../../../assets/customprovider4.png)
+
+Common endpoints for popular services:
+- **Together AI:** `https://api.together.xyz/`
+- **Fireworks:** `https://api.fireworks.ai/`
+- **Replicate:** `https://api.replicate.com/`
+- **Local vLLM:** `http://localhost:8000/` (default)
+- **LMStudio:** `http://localhost:1234/` (default)
+
+### Add Model IDs
+
+Click the `+` button to add specific models you want to access. Each provider offers different models with various capabilities.
+
+![Add model ID modal](../../../assets/customprovider5.png)
+
+For Together AI, we're adding `Qwen/Qwen3-235B-A22B-Thinking-2507`, one of the most capable reasoning models available.
+
+### Configure Model Features
+
+After adding a model, click the pencil icon to enable additional features like tools or vision capabilities.
+
+![Model configuration icon](../../../assets/customprovider6.png)
+
+Enable tools if your model supports function calling. This allows integration with Jan's MCP system for web search, code execution, and more.
+
+![Enable tools modal](../../../assets/customprovider7.png)
+
+### Start Using Your Custom Model
+
+Open a new chat and select your custom model from the provider dropdown.
+
+![Model selection in chat](../../../assets/customprovider8.png)
+
+If you enabled tools, click the tools icon to activate MCP integrations. Here we have Serper MCP enabled for web search capabilities.
+
+![Tools enabled in chat](../../../assets/customprovider9.png)
+
+<Aside type="note">
+Learn how to set up web search with our [Serper MCP tutorial](./mcp-examples/search/serper).
+</Aside>
+
+### Example in Action
+
+Here's the Qwen model thinking through a complex query, searching the web, and providing detailed information about Sydney activities.
+
+![Example conversation](../../../assets/customprovider10.png)
+
+**Prompt used:** "What is happening in Sydney, Australia this week? What fun activities could I attend?"
+
+The model demonstrated reasoning, web search integration, and comprehensive response formatting—all through Jan's custom provider system.
+
+## Provider-Specific Setup
+
+### Together AI
+- **Endpoint:** `https://api.together.xyz/`
+- **Popular Models:** `meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo`, `Qwen/Qwen2.5-Coder-32B-Instruct`
+- **Features:** Fast inference, competitive pricing, latest models
+- **Best For:** Production applications, latest model access
+
+### Fireworks AI
+- **Endpoint:** `https://api.fireworks.ai/`
+- **Popular Models:** `accounts/fireworks/models/llama-v3p1-405b-instruct`, `accounts/fireworks/models/qwen2p5-coder-32b-instruct`
+- **Features:** Ultra-fast inference, function calling support
+- **Best For:** Real-time applications, tool usage
+
+### vLLM (Local)
+- **Endpoint:** `http://localhost:8000/` (configurable)
+- **Setup:** Install vLLM, run `vllm serve MODEL_NAME --api-key YOUR_KEY`
+- **Models:** Any HuggingFace model compatible with vLLM
+- **Best For:** Self-hosted deployments, custom models
+
+### LMStudio (Local)
+- **Endpoint:** `http://localhost:1234/` (default)
+- **Setup:** Download LMStudio, load a model, start local server
+- **Models:** GGUF models from HuggingFace
+- **Best For:** Easy local setup, GUI management
+
+### Ollama (Local)
+- **Endpoint:** `http://localhost:11434/` (with OpenAI compatibility)
+- **Setup:** Install Ollama, run `OLLAMA_HOST=0.0.0.0 ollama serve`
+- **Models:** Ollama model library (llama3, qwen2.5, etc.)
+- **Best For:** Simple local deployment, model management
+
+## Example Prompts to Try
+
+### Advanced Reasoning
+```
+I'm planning to start a sustainable urban garden on my apartment balcony. Consider my location (temperate climate), space constraints (4x6 feet), budget ($200), and goals (year-round fresh herbs and vegetables). Provide a detailed plan including plant selection, container setup, watering system, and seasonal rotation schedule.
+```
+
+### Research and Analysis
+```
+Compare the environmental impact of electric vehicles vs hydrogen fuel cell vehicles in 2024. Include manufacturing emissions, energy sources, infrastructure requirements, and lifecycle costs. Provide specific data and cite recent studies.
+```
+
+### Creative Problem Solving
+```
+Design a mobile app that helps people reduce food waste. Consider user psychology, practical constraints, monetization, and social impact. Include wireframes description, key features, and go-to-market strategy.
+```
+
+### Technical Deep Dive
+```
+Explain how large language models use attention mechanisms to understand context. Start with the basics and build up to transformer architecture, including mathematical foundations and practical implications for different model sizes.
+```
+
+### Planning and Strategy
+```
+I have 6 months to learn machine learning from scratch and land an ML engineering job. Create a week-by-week study plan including theory, practical projects, portfolio development, and job search strategy. Consider my background in software development.
+```
+
+## Advanced Configuration
+
+### Authentication Methods
+
+**API Key Header (Most Common):**
+- Standard: `Authorization: Bearer YOUR_KEY`
+- Custom: `X-API-Key: YOUR_KEY`
+
+**Query Parameters:**
+- Some services use `?api_key=YOUR_KEY`
+
+**Custom Headers:**
+- Enterprise gateways may require specific headers
+
+### Request Customization
+
+Most providers support OpenAI's standard parameters:
+- `temperature`: Response creativity (0.0-1.0)
+- `max_tokens`: Response length limit
+- `top_p`: Token selection probability
+- `frequency_penalty`: Repetition control
+- `presence_penalty`: Topic diversity
+
+### Model Naming Conventions
+
+Different providers use various naming schemes:
+- **HuggingFace:** `organization/model-name`
+- **Together AI:** `meta-llama/Llama-2-70b-chat-hf`
+- **Ollama:** `llama3:latest`
+- **Local:** Often just the model name
+
+## Troubleshooting
+
+### Connection Issues
+- Verify the API endpoint URL is correct
+- Check if the service is running (for local providers)
+- Confirm network connectivity and firewall settings
+
+### Authentication Failures
+- Ensure API key is copied correctly (no extra spaces)
+- Check if the key has necessary permissions
+- Verify the authentication method matches provider requirements
+
+### Model Not Found
+- Confirm the model ID exists on the provider
+- Check spelling and capitalization
+- Some models require special access or approval
+
+### Rate Limiting
+- Most providers have usage limits
+- Implement delays between requests if needed
+- Consider upgrading to higher tier plans
+
+### Performance Issues
+- Local providers may need more powerful hardware
+- Cloud providers vary in response times
+- Check provider status pages for service issues
+
+## Cost Management
+
+### Cloud Provider Pricing
+- Most charge per token (input + output)
+- Prices vary significantly between models
+- Monitor usage through provider dashboards
+
+### Local Provider Costs
+- Hardware requirements (RAM, GPU)
+- Electricity consumption
+- Initial setup and maintenance time
+
+### Optimization Tips
+- Use smaller models for simple tasks
+- Implement caching for repeated queries
+- Set appropriate max_tokens limits
+- Monitor and track usage patterns
+
+## Best Practices
+
+### Security
+- Store API keys securely
+- Use environment variables in production
+- Rotate keys regularly
+- Monitor for unauthorized usage
+
+### Performance
+- Choose models appropriate for your tasks
+- Implement proper error handling
+- Cache responses when possible
+- Use streaming for long responses
+
+### Reliability
+- Have fallback providers configured
+- Implement retry logic
+- Monitor service availability
+- Test regularly with different models
+
+## Next Steps
+
+Once you have custom providers configured, explore advanced integrations:
+- Combine with [MCP tools](./mcp-examples/search/serper) for enhanced capabilities
+- Set up multiple providers for different use cases
+- Create custom assistants with provider-specific models
+- Build workflows that leverage different model strengths
+
+Custom providers unlock Jan's full potential, letting you access cutting-edge models and maintain complete control over your AI infrastructure. Whether you prefer cloud convenience or local privacy, Jan adapts to your workflow.

website/src/content/docs/jan/explanation/llama-cpp.mdx

@@ -1,207 +0,0 @@
----
-title: Local AI Engine
-description: Understand and configure Jan's local AI engine for running models on your hardware.
-keywords:
-  [
-    Jan,
-    Customizable Intelligence, LLM,
-    local AI,
-    privacy focus,
-    free and open source,
-    private and offline,
-    conversational AI,
-    no-subscription fee,
-    large language models,
-    Llama CPP integration,
-    llama.cpp Engine,
-    Intel CPU,
-    AMD CPU,
-    NVIDIA GPU,
-    AMD GPU Radeon,
-    Apple Silicon,
-    Intel Arc GPU,
-  ]
----
-
-import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
-
-## What is llama.cpp?
-
-llama.cpp is the engine that runs AI models locally on your computer. Think of it as the software
-that takes an AI model file and makes it work on your hardware - whether that's your CPU,
-graphics card, or Apple's M-series chips.
-
-Originally created by Georgi Gerganov, llama.cpp is designed to run large language models
-efficiently on consumer hardware without requiring specialized AI accelerators or cloud connections.
-
-## Why This Matters
-
-- **Privacy**: Your conversations never leave your computer
-- **Cost**: No monthly subscription fees or API costs
-- **Speed**: No internet required once models are downloaded
-- **Control**: Choose exactly which models to run and how they behave
-
-## Accessing Engine Settings
-
-Find llama.cpp settings at **Settings** > **Model Providers** > **Llama.cpp**:
-
-![llama.cpp](../../../../assets/llama.cpp-01-updated.png)
-
-<Aside type="note">
-These are advanced settings. You typically only need to adjust them if models aren't working properly or you want to optimize performance for your specific hardware.
-</Aside>
-
-## Engine Management
-
-| Feature | What It Does | When You Need It |
-|---------|-------------|------------------|
-| **Engine Version** | Shows which version of llama.cpp you're running | Check compatibility with newer models |
-| **Check Updates** | Downloads newer engine versions | When new models require updated engine |
-| **Backend Selection** | Choose the version optimized for your hardware | After installing new graphics cards or when performance is poor |
-
-## Hardware Backends
-
-Jan offers different backend versions optimized for your specific hardware. Think of these as different "drivers" - each one is tuned for particular processors or graphics cards.
-
-<Aside type="caution">
-Using the wrong backend can make models run slowly or fail to load. Pick the one that matches your hardware.
-</Aside>
-
-<Tabs>
-
-<TabItem label="Windows">
-
-### NVIDIA Graphics Cards (Recommended for Speed)
-Choose based on your CUDA version (check NVIDIA Control Panel):
-
-**For CUDA 12.0:**
-- `llama.cpp-avx2-cuda-12-0` (most common)
-- `llama.cpp-avx512-cuda-12-0` (newer Intel/AMD CPUs)
-
-**For CUDA 11.7:**
-- `llama.cpp-avx2-cuda-11-7` (most common)
-- `llama.cpp-avx512-cuda-11-7` (newer Intel/AMD CPUs)
-
-### CPU Only (No Graphics Card Acceleration)
-- `llama.cpp-avx2` (most modern CPUs)
-- `llama.cpp-avx512` (newer Intel/AMD CPUs)
-- `llama.cpp-avx` (older CPUs)
-- `llama.cpp-noavx` (very old CPUs)
-
-### Other Graphics Cards
-- `llama.cpp-vulkan` (AMD, Intel Arc, some others)
-
-<Aside type="note">
-**Quick Test**: Start with `avx2-cuda-12-0` if you have an NVIDIA card, or `avx2` for CPU-only. If it doesn't work, try the `avx` variant.
-</Aside>
-
-</TabItem>
-
-<TabItem label="Linux">
-
-### NVIDIA Graphics Cards
-Same CUDA options as Windows:
-- `llama.cpp-avx2-cuda-12-0` (most common)
-- `llama.cpp-avx2-cuda-11-7` (older drivers)
-
-### CPU Only
-- `llama.cpp-avx2` (most modern CPUs)
-- `llama.cpp-avx512` (newer Intel/AMD CPUs)
-- `llama.cpp-arm64` (ARM processors like Raspberry Pi)
-
-### Other Graphics Cards
-- `llama.cpp-vulkan` (AMD, Intel graphics)
-
-</TabItem>
-
-<TabItem label="MacOS">
-
-### Apple Silicon (M1/M2/M3/M4)
-- `llama.cpp-mac-arm64` (recommended)
-
-### Intel Macs
-- `llama.cpp-mac-amd64`
-
-<Aside type="note">
-Apple Silicon Macs automatically use the GPU through Metal - no additional setup needed.
-</Aside>
-
-</TabItem>
-
-</Tabs>
-
-## Performance Settings
-
-These control how efficiently models run:
-
-| Setting | What It Does | Recommended Value | Impact |
-|---------|-------------|------------------|---------|
-| **Continuous Batching** | Process multiple requests at once | Enabled | Faster when using multiple tools or having multiple conversations |
-| **Parallel Operations** | How many requests to handle simultaneously | 4 | Higher = more multitasking, but uses more memory |
-| **CPU Threads** | How many processor cores to use | Auto-detected | More threads can speed up CPU processing |
-
-## Memory Settings
-
-These control how models use your computer's memory:
-
-| Setting | What It Does | Recommended Value | When to Change |
-|---------|-------------|------------------|----------------|
-| **Flash Attention** | More efficient memory usage | Enabled | Leave enabled unless you have problems |
-| **Caching** | Remember recent conversations | Enabled | Speeds up follow-up questions |
-| **KV Cache Type** | Memory precision trade-off | f16 | Change to q8_0 or q4_0 if running out of memory |
-| **mmap** | Load models more efficiently | Enabled | Helps with large models |
-| **Context Shift** | Handle very long conversations | Disabled | Enable for very long chats or multiple tool calls |
-
-### KV Cache Types Explained
-- **f16**: Most stable, uses more memory
-- **q8_0**: Balanced memory usage and quality
-- **q4_0**: Uses least memory, slight quality loss
-
-## Troubleshooting Common Issues
-
-**Models won't load:**
-- Try a different backend (switch from CUDA to CPU or vice versa)
-- Check if you have enough RAM/VRAM
-- Update to latest engine version
-
-**Very slow performance:**
-- Make sure you're using GPU acceleration (CUDA/Metal/Vulkan backend)
-- Increase GPU Layers in model settings
-- Close other memory-intensive programs
-
-**Out of memory errors:**
-- Reduce Context Size in model settings
-- Switch KV Cache Type to q8_0 or q4_0
-- Try a smaller model variant
-
-**Random crashes:**
-- Switch to a more stable backend (try avx instead of avx2)
-- Disable overclocking if you have it enabled
-- Update graphics drivers
-
-## Quick Setup Guide
-
-**For most users:**
-1. Use the default backend that Jan installs
-2. Leave all performance settings at defaults
-3. Only adjust if you experience problems
-
-**If you have an NVIDIA graphics card:**
-1. Download the appropriate CUDA backend
-2. Make sure GPU Layers is set high in model settings
-3. Enable Flash Attention
-
-**If models are too slow:**
-1. Check you're using GPU acceleration
-2. Try enabling Continuous Batching
-3. Close other applications using memory
-
-**If running out of memory:**
-1. Change KV Cache Type to q8_0
-2. Reduce Context Size in model settings
-3. Try a smaller model
-
-<Aside type="note">
-Most users can run Jan successfully without changing any of these settings. The defaults are chosen
-to work well on typical hardware.
-</Aside>

website/src/content/docs/jan/explanation/model-parameters.mdx

@@ -18,8 +18,6 @@ keywords:
 ---
 import { Aside, Steps } from '@astrojs/starlight/components'
 
-# Model Parameters
-
 Model parameters control how your AI thinks and responds. Think of them as the AI's personality settings and performance controls.
 
 ## How to Access Settings

website/src/content/docs/jan/installation/linux.mdx

@@ -174,8 +174,6 @@ Configuration for GPU support:
 
 <Tabs>
   <TabItem label="NVIDIA GPU">
-    <ol>
-
     ### Step 1: Verify Hardware & Install Dependencies
 
     **1.1. Check GPU Detection**
@@ -221,8 +219,6 @@ Configuration for GPU support:
     <Aside type="note">
     CUDA offers better performance than Vulkan.
     </Aside>
-
-    </ol>
   </TabItem>
 
   <TabItem label="AMD GPU">

website/src/content/docs/jan/jan-models/jan-nano-32.mdx

@@ -20,7 +20,6 @@ sidebar:
 
 import { Aside } from '@astrojs/starlight/components';
 
-![Jan Nano](../../../../assets/jan-nano0.png)
 
 ## Why Jan Nano?
 

website/src/content/docs/jan/jan-models/lucy.mdx

@@ -5,7 +5,6 @@ description: Compact 1.7B model optimized for web search with tool calling
 
 import { Aside } from '@astrojs/starlight/components';
 
-![Lucy](../../../../assets/lucy.jpeg)
 
 ## Overview
 
@@ -13,8 +12,6 @@ Lucy is a 1.7B parameter model built on Qwen3-1.7B, optimized for web search thr
 
 ## Performance
 
-### SimpleQA Benchmark
-
 Lucy achieves competitive performance on SimpleQA despite its small size:
 
 ![Lucy SimpleQA Performance](../../../../assets/simpleqa_lucy.png)
@@ -23,7 +20,7 @@ The benchmark shows Lucy (1.7B) compared against models ranging from 4B to 600B+
 
 ## Requirements
 
-- **Memory**: 
+- **Memory**:
   - Minimum: 4GB RAM (with Q4 quantization)
   - Recommended: 8GB RAM (with Q8 quantization)
 - **Search API**: Serper API key required for web search functionality
@@ -100,12 +97,12 @@ Min-p: 0.0
 
 ```bibtex
 @misc{dao2025lucyedgerunningagenticweb,
-      title={Lucy: edgerunning agentic web search on mobile with machine generated task vectors}, 
+      title={Lucy: edgerunning agentic web search on mobile with machine generated task vectors},
       author={Alan Dao and Dinh Bach Vu and Alex Nguyen and Norapat Buppodom},
       year={2025},
       eprint={2508.00360},
       archivePrefix={arXiv},
       primaryClass={cs.CL},
-      url={https://arxiv.org/abs/2508.00360}, 
+      url={https://arxiv.org/abs/2508.00360},
 }
 ```

website/src/content/docs/jan/manage-models.mdx

@@ -1,43 +1,47 @@
 ---
-title: Managing Models
-description: Manage your interaction with AI models locally.
+title: Models Overview
+description: Manage AI models in Jan - local and cloud options
 keywords:
   [
     Jan,
-    Customizable Intelligence, LLM,
-    local AI,
-    privacy focus,
-    free and open source,
-    private and offline,
-    conversational AI,
-    no-subscription fee,
-    large language models,
-    threads,
-    chat history,
-    thread history,
+    AI models,
+    local models,
+    cloud models,
+    GGUF,
+    Llama.cpp,
+    model management,
+    OpenAI,
+    Anthropic,
+    model selection,
+    hardware requirements,
+    privacy,
   ]
 ---
 
 import { Aside } from '@astrojs/starlight/components';
 
-This guide shows you how to add, customize, and delete models within Jan.
+AI models power Jan's conversations. You can run models locally on your device for privacy, or connect to cloud providers for more power.
 
-## Local Model
+## Quick Start
 
-Local models are managed through [Llama.cpp](https://github.com/ggerganov/llama.cpp), and these models are in a
-format called GGUF. When you run them locally, they will use your computer's memory (RAM) and processing power, so
-please make sure that you download models that match the hardware specifications for your operating system:
+**New to Jan?** Start with **Jan-v1** (4B) - it runs on most computers
+**Limited hardware?** Use cloud models with your API keys
+**Privacy focused?** Download any local model - your data never leaves your device
+
+## Local Models
+
+Local models are managed through [Llama.cpp](https://github.com/ggerganov/llama.cpp), and these models are in a format called GGUF. When you run them locally, they will use your computer's memory (RAM) and processing power, so please make sure that you download models that match the hardware specifications for your operating system:
 - [Mac](/docs/desktop/mac#compatibility)
 - [Windows](/docs/desktop/windows#compatibility)
-- [Linux](/docs/desktop/linux#compatibility).
+- [Linux](/docs/desktop/linux#compatibility)
 
-### Adding Models
+### Adding Local Models
 
 #### 1. Download from Jan Hub (Recommended)
 
-The easiest way to get started is using Jan's built-in model hub (which is connected to [HuggingFace's Model Hub](https://huggingface.co/models):
+The easiest way to get started is using Jan's built-in model hub (connected to [HuggingFace's Model Hub](https://huggingface.co/models)):
 1. Go to the **Hub** tab
-2. Browse available models and click on any model to see details about it
+2. Browse available models and click on any model to see details
 3. Choose a model that fits your needs & hardware specifications
 4. Click **Download** on your chosen model
 
@@ -47,141 +51,140 @@ Jan will indicate if a model might be **Slow on your device** or **Not enough RA
 
 ![Download Model](../../../assets/model-management-01.png)
 
-
-#### 2. Import from [Hugging Face](https://huggingface.co/)
+#### 2. Import from Hugging Face
 
 You can download models with a direct link from Hugging Face:
 
 **Note:** Some models require a Hugging Face Access Token. Enter your token in **Settings > Model Providers > Hugging Face** before importing.
 
-1. Visit the [Hugging Face Models](https://huggingface.co/models) page.
-2. Find the model you want to use, make sure it is a GGUF file that fits in your computer.
+1. Visit [Hugging Face Models](https://huggingface.co/models)
+2. Find a GGUF model that fits your computer
 3. Copy the **model ID** (e.g., TheBloke/Mistral-7B-v0.1-GGUF)
 4. In Jan, paste the model ID to the **Search** bar in **Hub** page
-5. Select your preferred quantized version to download (if the option is available)
+5. Select your preferred quantized version to download
 
-**Copy the model ID.**
+**Copy the model ID:**
 ![Find HF Model](../../../assets/hf-unsloth.png)
 
-**Paste it in Jan's Hub Search Bar.**
+**Paste it in Jan's Hub Search Bar:**
 ![Import Model](../../../assets/model-management-02.png)
 
 #### 3. Import Local Files
 
-If you already have one or many GGUF model files on your computer:
-1. In Jan, go to **Settings > Model Providers > Llama.cpp**
+If you already have GGUF model files on your computer:
+1. Go to **Settings > Model Providers > Llama.cpp**
 2. Click **Import** and select your GGUF file(s)
-3. Choose how you want to import:
-  - **Link Files:** Creates symbolic links to your model files (saves space)
-  - **Duplicate:** Makes a copy of model files in Jan's directory
-4. Click **Import** to complete (check the [Jan Data Folder](./data-folder) section for more info)
-
-<Aside type="caution">
-You need to own your **model configurations**, use at your own risk. Misconfigurations may result in lower
-quality or unexpected outputs. Learn about [model configurations here](./model-parameters).
-</Aside>
-
-![Download Model](../../../assets/model-management-04.png)
-
-![Download Model](../../../assets/model-import-04.png)
-
-![Download Model](../../../assets/model-import-05.png)
+3. Choose how to import:
+   - **Link Files:** Creates symbolic links (saves space)
+   - **Duplicate:** Copies files to Jan's directory
+4. Click **Import** to complete
 
+![Import Settings](../../../assets/model-management-04.png)
+![Import Dialog](../../../assets/model-import-04.png)
+![Import Options](../../../assets/model-import-05.png)
 
 #### 4. Manual Setup
 
-For advanced users who want to add a specific model that is not available within the Jan **Hub**:
+For advanced users who want to add models not available in Jan Hub:
 
 ##### Step 1: Create Model File
 
 1. Navigate to the [Jan Data Folder](./data-folder)
 2. Open `models` folder
-3. Create a new **Folder** for your model
+3. Create a new folder for your model
 4. Add your `model.gguf` file
-5. Add your `model.json` file with your configuration. Here's an example with "TinyLlama Chat 1.1B Q4":
+5. Add a `model.yml` configuration file. Example:
 
-```json
-{
-  "sources": [
-    {
-      "filename": "tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf",
-      "url": "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
-    }
-  ],
-  "id": "tinyllama-1.1b",
-  "object": "model",
-  "name": "TinyLlama Chat 1.1B Q4",
-  "version": "1.0",
-  "description": "TinyLlama is a tiny model with only 1.1B. It's a good model for less powerful computers.",
-  "format": "gguf",
-  "settings": {
-    "ctx_len": 4096,
-    "prompt_template": "<|system|>\n{system_message}<|user|>\n{prompt}<|assistant|>",
-    "llama_model_path": "tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
-  },
-  "parameters": {
-    "temperature": 0.7,
-    "top_p": 0.95,
-    "stream": true,
-    "max_tokens": 2048,
-    "stop": [],
-    "frequency_penalty": 0,
-    "presence_penalty": 0
-  },
-  "metadata": {
-    "author": "TinyLlama",
-    "tags": [
-      "Tiny",
-      "Foundation Model"
-    ],
-    "size": 669000000
-  },
-  "engine": "nitro"
-}
-```
-##### Step 2: Modify Model Parameters
-
-Key fields to configure:
-1. The **Settings** array is where you can set the path or location of your model in your computer, the context
-length allowed, and the chat template expected by your model.
-2. The [**Parameters**](./model-parameters) are the adjustable settings that affect how your model operates or
-processes the data. The fields in the parameters array are typically general and can be used across different
-models. Here is an example of model parameters:
-
-```json
-"parameters":{
-  "temperature": 0.7,
-  "top_p": 0.95,
-  "stream": true,
-  "max_tokens": 4096,
-  "frequency_penalty": 0,
-  "presence_penalty": 0,
-}
+```yaml
+model_path: llamacpp/models/Jan-v1-4B-Q4_K_M/model.gguf
+name: Jan-v1-4B-Q4_K_M
+size_bytes: 2497281632
 ```
 
-### Delete Models
+That's it! Jan now uses a simplified YAML format. All other parameters (temperature, context length, etc.) can be configured directly in the UI when you select the model.
+
+##### Step 2: Customize in the UI
+
+Once your model is added:
+1. Select it in a chat
+2. Click the gear icon next to the model
+3. Adjust any parameters you need
+
+<Aside type="note">
+The simplified `model.yml` format makes model management easier. All advanced settings are now accessible through Jan's UI rather than requiring manual JSON editing.
+</Aside>
+
+### Delete Local Models
+
 1. Go to **Settings > Model Providers > Llama.cpp**
 2. Find the model you want to remove
-3. Select the three dots icon next to it and select **Delete Model**
+3. Click the three dots icon and select **Delete Model**
 
 ![Delete Model](../../../assets/model-management-05.png)
 
 ## Cloud Models
 
+Jan supports connecting to various AI cloud providers through OpenAI-compatible APIs, including OpenAI (GPT-4o, o1), Anthropic (Claude), Groq, Mistral, and more.
+
 <Aside type="note">
-When using cloud models, be aware of any associated costs and rate limits from the providers. See detailed guide for
-each cloud model provider [here](./remote-models/anthropic).
+When using cloud models, be aware of associated costs and rate limits from the providers. See detailed guides for each provider in the [Cloud Providers section](./remote-models/anthropic).
 </Aside>
 
-Jan supports connecting to various AI cloud providers that are OpenAI API-compatible, including: OpenAI (GPT-4o, o3,...),
-Anthropic (Claude), Groq, Mistral, and more.
-1. Navigate to the **Settings** page
-2. Under **Model Providers** section in the left sidebar, choose your preferred provider (OpenAI, Anthropic, etc.)
+### Setting Up Cloud Models
+
+1. Navigate to **Settings**
+2. Under **Model Providers** in the left sidebar, choose your provider
 3. Enter your API key
-4. The activated cloud models will be available in your model selector inside the **Chat** panel
+4. Activated cloud models appear in your model selector
 
-![Download Model](../../../assets/model-management-06.png)
+![Cloud Provider Settings](../../../assets/model-management-06.png)
 
-As soon as you add your key for a model provider like Anthropic or OpenAI, you will be able to pick one of their models to chat with.
+Once you add your API key, you can select any of that provider's models in the chat interface:
 
-![Connect Remote APIs](../../../assets/quick-start-03.png)
+![Select Cloud Model](../../../assets/quick-start-03.png)
+
+## Choosing Between Local and Cloud
+
+### Local Models
+**Best for:**
+- Privacy-sensitive work
+- Offline usage
+- Unlimited conversations without costs
+- Full control over model behavior
+
+**Requirements:**
+- 8GB RAM minimum (16GB+ recommended)
+- 10-50GB storage per model
+- CPU or GPU for processing
+
+### Cloud Models
+**Best for:**
+- Advanced capabilities (GPT-4, Claude 3)
+- Limited hardware
+- Occasional use
+- Latest model versions
+
+**Requirements:**
+- Internet connection
+- API keys from providers
+- Usage-based payment
+
+## Hardware Guidelines
+
+| RAM | Recommended Model Size |
+|-----|----------------------|
+| 8GB | 1-3B parameters |
+| 16GB | 7B parameters |
+| 32GB | 13B parameters |
+| 64GB+ | 30B+ parameters |
+
+<Aside type="tip">
+Start with smaller models and upgrade as needed. Jan shows compatibility warnings before downloading.
+</Aside>
+
+## Next Steps
+
+- [Explore Jan Models](./jan-models/jan-v1) - Our optimized models
+- [Set up Cloud Providers](./remote-models/openai) - Connect external services
+- [Learn Model Parameters](./explanation/model-parameters) - Fine-tune behavior
+- [Create AI Assistants](./assistants) - Customize models with instructions

website/src/content/docs/jan/mcp-examples/data-analysis/e2b.mdx

@@ -40,10 +40,6 @@ complexity of managing Python environments or dependencies locally.
 
 ![Turn on MCP](../../../../../assets/mcp-on.png)
 
-<Aside type="note">
-Don't forget that MCP gets enabled once you turn on Experimental Features in Jan's General settings.
-</Aside>
-
 2. **Get API Key**: Sign up at [e2b.dev](https://e2b.dev/), generate an API key
 
 ![E2B API Key](../../../../../assets/e2b-key.png)

website/src/content/docs/jan/mcp-examples/productivity/linear.mdx

@@ -56,7 +56,6 @@ Linear MCP offers extensive project management capabilities:
 
 ## Prerequisites
 
-- Jan with experimental features enabled
 - Linear account (free for up to 250 issues)
 - Model with strong tool calling support
 - Active internet connection
@@ -80,10 +79,6 @@ Once logged in, you'll see your workspace:
 
 ### Enable MCP in Jan
 
-<Aside type="caution">
-Enable **Experimental Features** in **Settings > General** if you don't see the MCP Servers option.
-</Aside>
-
 1. Go to **Settings > MCP Servers**
 2. Toggle **Allow All MCP Tool Permission** ON
 

website/src/content/docs/jan/mcp-examples/productivity/todoist.mdx

@@ -32,7 +32,6 @@ import { Aside } from '@astrojs/starlight/components';
 
 ## Prerequisites
 
-- Jan with experimental features enabled
 - Todoist account (free or premium)
 - Model with strong tool calling support
 - Node.js installed
@@ -65,10 +64,6 @@ Once logged in, you'll see your main dashboard:
 
 ### Enable MCP in Jan
 
-<Aside type="caution">
-If you don't see the MCP Servers option, enable **Experimental Features** in **Settings > General** first.
-</Aside>
-
 1. Go to **Settings > MCP Servers**
 2. Toggle **Allow All MCP Tool Permission** ON
 

website/src/content/docs/jan/mcp-examples/search/serper.mdx

@@ -9,7 +9,9 @@ sidebar:
 
 import { Aside } from '@astrojs/starlight/components';
 
-[Serper](https://serper.dev) provides Google search results through a simple API, making it perfect for giving AI models access to current web information. The Serper MCP integration enables Jan models to search the web and retrieve real-time information.
+[Serper](https://serper.dev) provides Google search results through a simple API, making it
+perfect for giving AI models access to current web information. The Serper MCP integration
+enables Jan models to search the web and retrieve real-time information.
 
 ## Available Tools
 
@@ -18,7 +20,6 @@ import { Aside } from '@astrojs/starlight/components';
 
 ## Prerequisites
 
-- Jan with experimental features enabled
 - Serper API key from [serper.dev](https://serper.dev)
 - Model with tool calling support (recommended: Jan v1)
 
@@ -28,13 +29,6 @@ Serper offers 2,500 free searches upon signup - enough for extensive testing and
 
 ## Setup
 
-### Enable Experimental Features
-
-1. Go to **Settings** > **General**
-2. Toggle **Experimental Features** ON
-
-![Enable experimental features](../../../../../assets/enable_mcp.png)
-
 ### Enable MCP
 
 1. Go to **Settings** > **MCP Servers**
@@ -78,12 +72,7 @@ Jan v1 is optimized for tool calling and works excellently with Serper:
 
 ### Enable Tool Calling
 
-1. Go to **Settings** > **Model Providers** > **Llama.cpp**
-2. Find Jan v1 in your models list
-3. Click the edit icon
-4. Toggle **Tools** ON
-
-![Enable tools for Jan v1](../../../../../assets/toggle_tools.png)
+Tool calling is now enabled by default on Jan.
 
 ## Usage
 
@@ -102,7 +91,8 @@ What are the latest developments in quantum computing this week?
 
 **Comparative Analysis:**
 ```
-What are the main differences between the Rust programming language and C++? Be spicy, hot takes are encouraged. 😌
+What are the main differences between the Rust programming language and C++? Be spicy, hot
+takes are encouraged. 😌
 ```
 
 
@@ -140,12 +130,10 @@ What restaurants opened in San Francisco this month? Focus on Japanese cuisine.
 **No search results:**
 - Verify API key is correct
 - Check remaining credits at serper.dev
-- Ensure MCP server shows as active
 
 **Tools not appearing:**
-- Confirm experimental features are enabled
-- Verify tool calling is enabled for your model
 - Restart Jan after configuration changes
+- Ensure MCP Server shows as active
 
 **Poor search quality:**
 - Use more specific search terms
@@ -164,4 +152,6 @@ Each search query consumes one API credit. Monitor usage at serper.dev dashboard
 
 ## Next Steps
 
-Serper MCP enables Jan v1 to access current web information, making it a powerful research assistant. Combine with other MCP tools for even more capabilities - use Serper for search, then E2B for data analysis, or Jupyter for visualization.
+Serper MCP enables models to access current web information, making them powerful research
+assistants. Combine with other MCP tools for even more capabilities - use Serper for search,
+then E2B for data analysis, or Jupyter for visualization.

website/src/content/docs/jan/mcp.mdx

@@ -1,25 +1,39 @@
 ---
 title: Model Context Protocol
-description: Manage your interaction with AI locally.
+description: Extend Jan's capabilities with tools and external integrations through MCP.
 keywords:
   [
     Jan,
-    Customizable Intelligence, LLM,
+    MCP,
+    Model Context Protocol,
+    tools,
+    integrations,
+    AI tools,
     local AI,
     privacy focus,
     free and open source,
     private and offline,
     conversational AI,
-    no-subscription fee,
     large language models,
-    threads,
-    chat history,
-    thread history,
+    external APIs,
   ]
 ---
 
 import { Aside } from '@astrojs/starlight/components';
 
+## Tools in Jan
+
+Jan supports powerful tool integrations that extend your AI's capabilities beyond simple text generation. These tools are implemented through the **Model Context Protocol (MCP)**, allowing your AI to search the web, execute code, manage files, and interact with external services.
+
+**Available tool categories:**
+- **Web & Search** - Real-time web search, browser automation
+- **Code & Analysis** - Jupyter notebooks, code execution, data analysis  
+- **Productivity** - Task management, calendar integration, note-taking
+- **Creative** - Design tools, content generation, media manipulation
+- **File Management** - Document processing, file operations, data extraction
+
+Tools work with both local and cloud models, though compatibility varies. Cloud models like GPT-4 and Claude typically offer the best tool-calling performance, while newer local models are rapidly improving their tool capabilities.
+
 ```mermaid
 graph TD
     subgraph "What is MCP?"
@@ -62,139 +76,223 @@ graph TD
     style Templates fill:transparent
 ```
 
+## What is MCP?
 
-Jan now supports the **Model Context Protocol (MCP)**, an open standard designed to allow language models to
-interact with external tools and data sources.
+Jan supports the **Model Context Protocol (MCP)**, an open standard that allows AI models to interact with external tools and data sources in a secure, standardized way.
 
-MCPs act as a common interface, standardizing the way an AI model can interact with external tools and data
-sources. This enables a model to connect to any MCP-compliant tool without requiring custom
-integration work. The way this works is via clients and servers. Clients are connected to an AI model and a host
-where a user will describe the task needed to be done. These applications hosting client will want to connect
-to different data sources to accomplish a task, for example, notion, google sheets, or even custom APIs. These
-applications will be connected to a server with prompts, tools, and data sources which will be used to complete
-the task.
+MCP solves the integration challenge by creating a common interface between AI models and external tools. Instead of building custom connectors for every model-tool combination, MCP provides a universal protocol that any compatible model can use with any compatible tool.
 
-Jan is an MCP host that allows you to download different clients and servers and use them to accomplish a task.
+**How it works:**
+- **MCP Servers** provide tools, data sources, and capabilities
+- **MCP Clients** (like Jan) connect models to these servers
+- **Standardized Protocol** ensures compatibility across different implementations
 
-This document outlines the benefits, risks, and implementation of MCPs within Jan.
+This architecture means you can easily add new capabilities to your AI without complex integrations, and tools built for one AI system work with others that support MCP.
 
-## Core Benefits of MCP
+## Core Benefits
 
-Integrating MCP provides a structured way to extend the capabilities of the models you use in Jan. Here are the three
+**Standardization:** MCP eliminates the "M x N" integration problem where every AI model needs unique connectors for every tool. One standard interface works everywhere.
 
-* **Standardization:** MCP aims to solve the "M x N" integration problem, where every model (M) needs a
-unique connector for every tool (N). By adapting to a single standard, any compliant model can interface with any compliant tool.
-* **Extensibility:** This allows you to augment your models with new abilities. For instance, an AI can be granted
-access to search your local codebase, query a database, or interact with web APIs, all through the same protocol.
-* **Flexibility:** Because the interface is standardized, you can swap out models or tools with minimal friction,
-making your workflows more modular and adaptable over time.
+**Extensibility:** Add powerful new capabilities to your AI models. Search local codebases, query databases, interact with web APIs, automate browser tasks, and more.
+
+**Flexibility:** Swap models and tools easily. Your MCP setup works whether you're using local models, Claude, GPT-4, or future AI systems.
+
+**Security:** User-controlled permissions ensure you decide which tools can access what resources. Tools run in isolated environments with explicit consent.
 
 <Aside type="caution">
-  Please note that not all models that you can download and use, whether in Jan or other tools, may be good at
-  tool calling or compatible with MCP. Make sure that the model you choose is MCP-compliant before integrating
-  it into your workflows. This might be available in the model card or you may need to implement it yourself to
-  test the capabilities of the model.
+Not all models excel at tool calling. For best results:
+- **Cloud models:** GPT-4, Claude 3.5+, and Gemini Pro offer excellent tool capabilities
+- **Local models:** Newer models like Qwen3, Gemma3, and function-calling variants work well
+- **Check compatibility:** Review model cards for tool-calling performance before setup
 </Aside>
 
+## Model Compatibility Requirements
+
 <Aside type="note">
-  To use MCP effectively, ensure your AI model supports tool calling capabilities:
-  - For cloud models (like Claude or GPT-4): Verify tool calling is enabled in your API settings
-  - For local models: Enable tool calling in the model parameters [click the edit button in Model Capabilities](/docs/model-parameters#model-capabilities-edit-button)
-  - Check the model's documentation to confirm MCP compatibility
+To use MCP tools effectively, ensure your model supports tool calling:
+
+**For cloud models:**
+- Enable tool calling in provider settings (usually automatic)
+- Verify API supports function calling endpoints
+- Check model-specific documentation for tool capabilities
+
+**For local models:**
+- Enable tool calling in model settings (gear icon → capabilities)
+- Choose models specifically trained for function calling
+- Monitor performance as tool complexity increases
 </Aside>
 
-## Considerations and Risks
+## Security and Considerations
 
-While powerful, MCP is an evolving standard, and its use requires careful consideration of the following points:
+MCP provides powerful capabilities that require careful security consideration:
 
-* **Security:** Granting a model access to external tools is a significant security consideration. A compromised
-tool or a malicious prompt could potentially lead to unintended actions or data exposure. Jan's implementation
-focuses on user-managed permissions to mitigate this risk, meaning, you have to turn on the permission for each
-tool individually.
-* **Standard Maturity:** As a relatively new protocol, best practices or sensible defaults are still being
-established. Users should be aware of potential issues like prompt injection, where an input could be crafted to
-misuse a tool's capabilities.
-* **Resource Management:** Active MCP connections may consume a portion of a model's context window, which could
-affect performance (i.e., the more tools the model and the larger the context of the conversation has the longer
-you will need to wait for a response). Efficient management of tools and their outputs is important.
+**Security Model:**
+- **Explicit permissions** for each tool and capability
+- **Isolated execution** prevents cross-tool interference
+- **User approval** required for sensitive operations
+- **Audit trails** track all tool usage and outputs
 
+**Performance Impact:**
+- **Context usage:** Active tools consume model context window space
+- **Response time:** More tools may slow generation slightly
+- **Resource usage:** Some tools require additional system resources
 
-## Configure and Use MCPs within Jan
+**Best Practices:**
+- Enable only tools you actively need
+- Review tool permissions regularly
+- Monitor system resource usage
+- Keep MCP servers updated for security patches
 
-To illustrate how MCPs can be used within Jan, we will walk through an example using the [Browser MCP](https://browsermcp.io/).
+## Setting Up MCP in Jan
 
-Before we begin, you will need to enable experimental features at `General` > `Advanced`. Next, go to `Settings` > `MCP Servers`, and toggle
-the `Allow All MCP Tool Permission` switch ON.
+### Prerequisites
 
-![Turn on the MCP Host](../../../assets/mcp-on.png)
+Ensure you have the required runtime environments:
+- **Node.js** - Download from [nodejs.org](https://nodejs.org/)
+- **Python** - Download from [python.org](https://www.python.org/)
 
-Please note that you will also need to have **NodeJS** and/or **Python** installed on your machine. In case you don't
-have either, you can download them from the official websites at the links below:
-- [Node.js](https://nodejs.org/)
-- [Python](https://www.python.org/)
+Most MCP tools require one or both of these environments.
 
+### Enable MCP Support
 
-### Browser MCP
+Navigate to **Settings → MCP Servers** and toggle **Allow All MCP Tool Permission** to ON.
 
-- Click on the `+` sign on the upper right-hand corner of the MCP box.
+![Enable MCP in Jan](../../../assets/mcp-on.png)
 
-![Add New Server](../../../assets/mcp-setup-1.png)
+This global setting allows Jan to connect to MCP servers. You'll still control individual tool permissions.
 
-- Enter the following details to configure the BrowserMCP:
-  - **Server Name**: `browsermcp`
-  - **Command**: `npx`
-  - **Arguments**: `@browsermcp/mcp`
-  - **Environment Variables**: You can leave this field empty.
+### Example: Browser MCP Setup
 
-![Configure BrowserMCP](../../../assets/mcp-setup-2.png)
+Let's configure Browser MCP for web automation as a practical example:
 
-- Check that the server has been activated successfully.
+#### Step 1: Add MCP Server
 
-![Server Confirmation](../../../assets/mcp-setup-3.png)
+Click the `+` button in the MCP Servers section:
 
-- Open your favorite chrome-based browser (e.g., Google Chrome, Brave, Vivaldi, Microsoft Edge, etc...) and navigate to the
-[Browser MCP Extension Page](https://chromewebstore.google.com/detail/browser-mcp-automate-your/bjfgambnhccakkhmkepdoekmckoijdlc).
+![Add new MCP server](../../../assets/mcp-setup-1.png)
 
-![Browser MCP Extension](../../../assets/mcp-setup-6.png)
+#### Step 2: Configure Browser MCP
 
-- Make sure to enable the extension to run on private windows. Since Browser Use will have access to all sites you've
-already logged into in your regular browser session, it is best to give it a clean slate to start from.
+Enter these details:
+- **Server Name:** `browsermcp`
+- **Command:** `npx`  
+- **Arguments:** `@browsermcp/mcp`
+- **Environment Variables:** Leave empty
 
-![Browser MCP Extension](../../../assets/mcp-setup-7.png)
+![Configure Browser MCP](../../../assets/mcp-setup-2.png)
 
-- Enable the extension to run on private windows by clicking on it and Connecting to the Browser MCP server.
+#### Step 3: Verify Connection
 
-![Browser MCP Extension](../../../assets/mcp-setup-8.png)
+Confirm the server shows as active:
 
-- Go back to Jan and pick a model with good tool use capabilities, for example, Claude 3.7 and 4 Sonnet, or Claude 4 Opus,
-and make sure to enable tool calling via the UI by going to **Model Providers > Anthropic** and, after you have entered your
-API key, enable tool from the **+** button.
+![Server confirmation](../../../assets/mcp-setup-3.png)
 
-![Browser MCP Extension](../../../assets/mcp-setup-9.png)
+#### Step 4: Install Browser Extension
 
-You can check and see if this was accurate below.
+Install the [Browser MCP Chrome Extension](https://chromewebstore.google.com/detail/browser-mcp-automate-your/bjfgambnhccakkhmkepdoekmckoijdlc) to enable browser control:
 
-![Browser MCP Extension](../../../assets/mcp-setup-10.png)
+![Browser MCP extension](../../../assets/mcp-setup-6.png)
 
+#### Step 5: Configure Extension
+
+Enable the extension for private browsing (recommended for clean sessions):
+
+![Extension private mode](../../../assets/mcp-setup-7.png)
+
+Connect the extension to your MCP server:
+
+![Extension connection](../../../assets/mcp-setup-8.png)
+
+#### Step 6: Enable Model Tools
+
+Select a model with strong tool-calling capabilities and enable tools:
+
+![Enable model tools](../../../assets/mcp-setup-9.png)
+
+Verify tool calling is active:
+
+![Verify tools enabled](../../../assets/mcp-setup-10.png)
+
+## Available MCP Integrations
+
+Jan supports a growing ecosystem of MCP tools:
+
+### Web & Search
+- **Browser Control** - Automate web browsing tasks
+- **Web Search** - Real-time search with Serper, Exa
+- **Screenshot** - Capture and analyze web content
+
+### Development
+- **Code Execution** - Run code in secure sandboxes
+- **GitHub** - Repository management and analysis
+- **Documentation** - Generate and maintain docs
+
+### Productivity  
+- **Task Management** - Todoist, Linear integration
+- **Calendar** - Schedule and meeting management
+- **Note Taking** - Obsidian, Notion connectivity
+
+### Creative
+- **Design Tools** - Canva integration for graphics
+- **Content Generation** - Blog posts, social media
+- **Media Processing** - Image and video manipulation
+
+Explore specific integrations in our [MCP Examples](./mcp-examples/browser/browserbase) section.
 
 ## Troubleshooting
 
-- The MCP server won't connect even though I've already added it to my list of MCP Servers?
-  - Make sure you have NodeJS and Python installed
-  - Make sure you typed the commands correctly in the MCP Server form
-  - Make sure the model you are using has tools enabled
-  - Restart Jan
-- The open source model I picked won't use the MCPs I enabled.
-  - Make sure the model you are using has tools enabled
-  - Lots of open source models are not designed to use tools or simply don't work well with them, so you may need to try a different model
-  - The model you have selected might be good at tool calling but it is possible that it does not support images, effectively making it unsuitable for some tools that take screenshots of a website like the Browser MCP
+### Connection Issues
 
-## Future Potential
+**MCP server won't connect:**
+- Verify Node.js and Python are installed correctly
+- Check command syntax in server configuration
+- Restart Jan after adding new servers
+- Review server logs for specific error messages
 
-This integration is the foundation for creating more capable and context-aware AI assistants within Jan. The
-long-term goal is to enable more sophisticated workflows that make use of your local environment securely as
-well as your favorite tools.
+**Tools not appearing:**
+- Ensure model has tool calling enabled
+- Verify MCP permissions are active
+- Check that the server status shows as running
+- Try with a different model known for good tool support
 
-For example, an AI could cross-reference information between a local document and a remote API, or use a
-local script toanalyze data and then summarize the findings, all orchestrated through Jan's interface. As
-the MCP ecosystem grows, so will the potential applications within Jan.
+### Performance Problems
+
+**Slow responses with tools:**
+- Reduce number of active tools
+- Use models with larger context windows
+- Monitor system resource usage
+- Consider using faster local models or cloud providers
+
+**Model not using tools effectively:**
+- Switch to models specifically trained for tool calling
+- Provide more explicit instructions about tool usage
+- Check model documentation for tool-calling examples
+- Test with proven tool-compatible models first
+
+### Model Compatibility
+
+**Local models not calling tools:**
+- Ensure the model supports function calling in its training
+- Enable tool calling in model capabilities settings
+- Try newer model versions with improved tool support
+- Consider switching to cloud models for complex tool workflows
+
+## Future Development
+
+MCP integration in Jan continues evolving with new capabilities:
+
+**Planned Features:**
+- **Visual tool builder** for custom MCP servers
+- **Tool marketplace** for easy discovery and installation  
+- **Enhanced security** with granular permission controls
+- **Performance optimization** for faster tool execution
+
+**Ecosystem Growth:**
+- More professional tools (CRM, analytics, design)
+- Better local model tool-calling performance
+- Cross-platform mobile tool support
+- Enterprise-grade security and compliance features
+
+The MCP ecosystem enables increasingly sophisticated AI workflows. As more tools become available and models improve their tool-calling abilities, Jan becomes a more powerful platform for augmented productivity and creativity.
+
+Start with simple tools like web search or code execution, then gradually expand your toolkit as you discover new use cases and workflows that benefit from AI-tool collaboration.