Mintplex-Labs · timothycarambat · Mar 31, 2025 · Mar 28, 2025 · Mar 28, 2025 · Mar 28, 2025
diff --git a/pages/_meta.json b/pages/_meta.json
@@ -145,6 +145,15 @@
     "type": "separator",
     "title": "Guides"
   },
+  "mcp-compatibility": {
+    "title": "MCP Compatibility",
+    "theme": {
+      "breadcrumb": true,
+      "footer": true,
+      "pagination": true,
+      "toc": true
+    }
+  },
   "agent-flows": {
     "title": "Agent Flows",
     "theme": {

diff --git a/pages/mcp-compatibility/_meta.json b/pages/mcp-compatibility/_meta.json
@@ -0,0 +1,29 @@
+{
+  "overview": {
+    "title": "Overview",
+    "theme": {
+      "breadcrumb": true,
+      "footer": true,
+      "pagination": true,
+      "toc": true
+    }
+  },
+  "docker": {
+    "title": "MCP on Docker",
+    "theme": {
+      "breadcrumb": true,
+      "footer": true,
+      "pagination": true,
+      "toc": true
+    }
+  },
+  "desktop": {
+    "title": "MCP on Desktop",
+    "theme": {
+      "breadcrumb": true,
+      "footer": true,
+      "pagination": true,
+      "toc": true
+    }
+  }
+}
diff --git a/pages/mcp-compatibility/desktop.mdx b/pages/mcp-compatibility/desktop.mdx
@@ -0,0 +1,12 @@
+---
+title: "MCP on AnythingLLM Desktop"
+description: "How to use and debug MCP tools on AnythingLLM Desktop"
+---
+
+import { Callout } from "nextra/components";
+
+## MCP on AnythingLLM Desktop
+
+The current version of AnythingLLM Desktop does not support MCP at this time.
+
+However, we are working on it! Join the [Discord server](https://discord.gg/Dh4zSZCdsC) or Star on [Github](https://github.com/Mintplex-Labs/anything-llm) to stay updated.
diff --git a/pages/mcp-compatibility/docker.mdx b/pages/mcp-compatibility/docker.mdx
@@ -0,0 +1,160 @@
+---
+title: "MCP on AnythingLLM Docker"
+description: "How to use and debug MCP tools on AnythingLLM Docker"
+---
+
+import { Callout } from "nextra/components";
+
+<Callout type="error" emoji="️‼️">
+  The use of MCP for AnythingLLM Docker is **self-hosting only** and is not available in the AnythingLLM Cloud service.
+</Callout>
+
+## Things to know about MCP on AnythingLLM Docker
+
+<Callout type="error" emoji="🔒">
+  As always, **never run MCPs you do not trust** - we **do not** endorse or guarantee the security of any MCPs you may find on the internet.
+</Callout>
+
+### MCP Server support
+
+AnythingLLM Docker supports `Tools` loading via MCP Servers. We **do not** support Resources, Prompts, or Sampling.
+
+### Startup sequence
+
+<Callout type="info" emoji="💡">
+  The more MCP servers you have defined, the longer it will take for them to start up. Your container should have enough resources to account for this.
+</Callout>
+
+AnythingLLM _does not_ automatically start MCP servers when the container starts to prevent any overloading of resources on boot.
+
+AnythingLLM _will_ automatically start MCP servers when you open the "Agent Skills" page in the AnythingLLM UI **or** invoke the `@agent` directive.
+All MCP servers will be started in the background - subsequent "boots" will then be much faster since the MCP servers will already be running.
+
+If you mark a tool as `anythingllm.autoStart: false` in your configuration file, it will not be started automatically - you will need to start it manually from the UI.
+
+### Command availability
+
+The majority of commands that are required to run a MCP server are available in the AnythingLLM Docker container already.
+
+The base image of AnythingLLM Docker is `ubuntu:jammy-20240627.1`, so generic Ubuntu commands will be available as the user running the services inside of the container.
+
+Additionally - we have pre-installed the following commands:
+- `npx`
+- `uv` or `uvx`
+- `node`
+- `bash`
+
+### Where is the MCP Server configuration file?
+
+The MCP Server configuration file is located in the `plugins/anythingllm_mcp_servers.json` file in the AnythingLLM storage directory.
+
+<Callout type="info" emoji="💡">
+  The configuration file is automatically created if you open the "Agent Skills" page in the AnythingLLM UI.
+</Callout>
+
+The storage directory is defined by the `STORAGE_LOCATION` environment variable when you start the AnythingLLM Docker container - [see example](/installation-docker/local-docker)
+
+### Reloading MCP Servers
+
+You can reload MCP Servers *on the fly* by clicking the "Refresh" button in the "Agent Skills" page. This will reload the MCP Servers from the configuration file and restart them. 
+This does not require you to restart the AnythingLLM Docker container - the currently running MCPs will be killed and rebooted with whatever changes you made to the configuration file.
+
+You can also click "Refresh" to reload the MCP Servers if you are debugging a specific MCP Server.
+
+### Starting and stopping MCP Servers
+
+You can start and stop MCP Servers *on the fly* by clicking the "Start" or "Stop" action via the gear icon in the "Agent Skills" page while selecting the MCP Server you want to start or stop.
+
+This does not require you to restart the AnythingLLM Docker container - the target MCP Server will be started or stopped immediately.
+
+If you wish to stop an MCP Server from automatically starting - see the [Autostart prevention](#autostart-prevention) section.
+
+### How do I add/remove an MCP Server?
+
+#### Adding an MCP Server
+Adding an MCP Server is as simple as adding a new tool to the `mcpServers` object in the `anythingllm_mcp_servers.json` file in your AnythingLLM storage directory.
+
+#### Removing an MCP Server
+
+You can remove an MCP Server by clicking on an MCP Server in the "Agent Skills" page, select the gear icon, and clicking "Delete".
+Deleting the MCP Server from the UI **will remove** the MCP Server from the file and kill the process running that MCP Server.
+
+You can also manually remove an MCP Server by removing the object from the `mcpServers` object in the `anythingllm_mcp_servers.json` file and clicking "Refresh" in the "Agent Skills" page on the UI afterwards.
+
+### Viewing the status of an MCP Server
+
+On the "Agent Skills" page, you can view the status of an MCP Server by clicking on the MCP Server in the list - if there is an error, it will be displayed in the card.
+
+Additionally, you can quickly see the status of all MCP Servers by clicking the "Agent Skills" page and looking at the MCP Servers list.
+
+### Debugging MCP Servers
+
+If you are having issues with an MCP Server, you can best debug these by looking at the docker container logs.
+
+### Issues installing a tool
+
+<Callout type="info" emoji="💡">
+  **Please do not open issues about tool issues on GitHub - we are not the MCP authors or maintainers.** 
+
+  If you are having issues, you should post on the [MCP Discussion board](https://github.com/orgs/modelcontextprotocol/discussions) - or ask in the AnythingLLM Discord server.
+</Callout>
+
+Sometimes, an MCP Server will require a tool to be installed via `uv tool install xyz`.
+The easiest way to do this is to open a shell into the container and run the command manually. Then you can click "Refresh" in the "Agent Skills" and see if the tool now boots successfully.
+
+### Autostart prevention
+
+_This property is **specific to AnythingLLM only** and will have no effect on other tools._
+
+Sometimes, you may want to optionally start an MCP server manually to prevent it from starting automatically and consuming resources.
+
+To do this, AnythingLLM respects the `anythingllm.autoStart` property in the MCP Server configuration file.
+
+For example, if you want to prevent the `face-generator` MCP Server from starting automatically, you can set the `autoStart` property to `false` in the configuration file.
+
+Any tool that does not have `autoStart: false` explicitly set will be started automatically when the rest of the MCP servers are started.
+
+```json
+{
+  "mcpServers": {
+    "face-generator": {
+      "command": "npx",
+      "args": [
+        "@dasheck0/face-generator"
+      ],
+      "anythingllm": {
+        "autoStart": false
+      }
+    },
+    "mcp-youtube": {
+      "command": "mcp-youtube",
+      "args": []
+    }
+  }
+}
+```
+
+### Tool persistence
+
+If you stop or delete the AnythingLLM Docker container the libraries cached for the MCP servers will be lost and need to be re-downloaded on first start. Typically, this takes much longer for MCP servers that have a large number of dependencies or build steps and can increase boot times when starting MCP servers.
+
+The also applies to any tools that you may have manually installed to get an MCP server to work - your changes are within the container and will be lost when the container is deleted.
+
+### Writing files to the host machine
+
+Often, you may want to write or even read files from the host machine - since the MCP Server runs within the context of the container - you **must** use this path:
+
+```
+/app/server/storage/...
+```
+
+This path will then be using the `STORAGE_LOCATION` directory that you defined when you [started the AnythingLLM Docker container](/installation-docker/local-docker). From here you can then write and read files to the host machine.
+
+
+### My LLM is not calling my MCP Server!
+
+First, ensure that the MCP Server is running and that the tool is available in the "Agent Skills" page.
+
+Next, your issue is probably the model you are using - this is especially true if you are using a small local model with a limited context window.
+
+[Learn more about LLMs with Agent Skills &rarr;](/agent-not-using-tools)
diff --git a/pages/mcp-compatibility/overview.mdx b/pages/mcp-compatibility/overview.mdx
@@ -0,0 +1,119 @@
+---
+title: "MCP Compatibility in AnythingLLM"
+description: "Use existing MCP Servers with AnythingLLM Agents"
+---
+
+import { Cards, Callout } from "nextra/components";
+import Image from "next/image";
+export const Card = Object.assign(
+  // Copy card component and add default props
+  Cards.Card.bind(),
+  {
+    displayName: "Card",
+    defaultProps: {
+      image: true,
+      arrow: true,
+      target: "_self",
+    },
+  }
+);
+
+<Image
+  src="/images/mcp-compatibility/mcp.png"
+  height={140}
+  width={846}
+  quality={100}
+  alt="Model Context Protocol"
+  style={{
+    borderRadius: "12px",
+    margin: "10px auto",
+  }}
+/>
+
+# Model Context Protocol (MCP) in AnythingLLM
+
+AnythingLLM supports the all [Model Context Protocol (MCP) tools](https://github.com/modelcontextprotocol/mcp-spec) for use with [AI Agents](/agent/overview).
+
+## What is MCP?
+
+MCP is and open-source protocol developed by [Anthropic](https://www.anthropic.com/) to enable seamless integration between LLM applications and external data sources and tools.
+
+There are [many tools](https://github.com/modelcontextprotocol/servers) that exist already built with MCP in mind and AnythingLLM can work with any of them.
+
+> The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
+
+## How to use MCP in AnythingLLM
+
+<Cards style={{
+  display: "flex",
+  flexDirection: "row",
+}}>
+  <Card title="AnythingLLM Docker" href="/mcp-compatibility/docker">
+    <Image
+      src="/images/mcp-compatibility/docker-header.png"
+      height={1080}
+      width={1920}
+      quality={100}
+    />
+  </Card>
+  <Card title="AnythingLLM Desktop" href="/mcp-compatibility/desktop">
+    <Image
+      src="/images/mcp-compatibility/desktop-header.png"
+      height={1080}
+      width={1920}
+      quality={100}
+    />
+  </Card>
+</Cards>
+
+
+MCP Servers can be added to AnythingLLM by editing the `anythingllm_mcp_servers.json` configuration file in your AnythingLLM storage `plugins` directory.
+
+The structure of the file is the same as the [MCP Server Specification](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#using-an-mcp-client).
+
+AnythingLLM will automatically detect the MCP Servers and attempt to boot them up as needed - you can also manage your servers directly in the AnythingLLM UI.
+
+### AnythingLLM MCP Configuration UI
+
+<Image
+  src="/images/mcp-compatibility/user-interface.png"
+  height={140}
+  width={846}
+  quality={100}
+  alt="Model Context Protocol"
+  style={{
+    borderRadius: "12px",
+    margin: "10px auto",
+  }}
+/>
+
+The MCP Management UI will show you all the MCP Servers that are available to use in AnythingLLM. You can also:
+- Reload/Restart all MCP Servers from the configuration file (if changes are made)
+- View the status of the MCP Servers found
+- View error logs from the MCP Servers
+- Stop or start the MCP Servers on the fly
+- View all available tools from the MCP Servers loaded successfully
+- Delete the MCP Servers (will remove the server from the configuration file)
+
+### Example configuration file
+
+_this file will be automatically generated in the proper directory if it doesn't exist before it is needed. It will be empty by default._
+
+```json
+{
+  "mcpServers": {
+    "face-generator": {
+      "command": "npx",
+      "args": [
+        "@dasheck0/face-generator"
+      ]
+    },
+    "mcp-youtube": {
+      "command": "uvx",
+      "args": [
+        "mcp-youtube"
+      ]
+    }
+  }
+}
+```
diff --git a/public/images/mcp-compatibility/desktop-header.png b/public/images/mcp-compatibility/desktop-header.png
diff --git a/public/images/mcp-compatibility/docker-header.png b/public/images/mcp-compatibility/docker-header.png
diff --git a/public/images/mcp-compatibility/mcp.png b/public/images/mcp-compatibility/mcp.png
diff --git a/public/images/mcp-compatibility/user-interface.png b/public/images/mcp-compatibility/user-interface.png
diff --git a/scripts/compress-images.mjs b/scripts/compress-images.mjs
@@ -27,6 +27,9 @@ function getInOut(input, output) {
   let dirs = getInOut(input, output);
 
   for (let item of dirs) {
+    // To target a specific directory to prevent duplicate compression, you can uncomment the following
+    // if (!item.input.includes("mcp-compatibility")) continue;
+
     console.log(`Processing ${item.input}`);
     const files = await imagemin([`${item.input}/*.{jpg,png}`], {
       destination: item.output,