ouranos/docs/anythingllm_mcp.md

AnythingLLM MCP Server Configuration

Overview

AnythingLLM supports Model Context Protocol (MCP) servers, allowing AI agents to call tools provided by local processes or remote services. MCP servers are managed by the internal MCPHypervisor singleton and configured via a single JSON file.

Configuration File Location

Environment	Path
Development	server/storage/plugins/anythingllm_mcp_servers.json
Production / Docker	$STORAGE_DIR/plugins/anythingllm_mcp_servers.json

The file and its parent directory are created automatically with an empty { "mcpServers": {} } object if they do not already exist.

File Format

{
  "mcpServers": {
    "<server-name>": { ... },
    "<server-name-2>": { ... }
  }
}

Each key inside mcpServers is the unique name used to identify the server within AnythingLLM. The value is the server definition, whose required fields depend on the transport type (see below).

---

Transport Types

stdio — Local Process

Spawns a local process and communicates over stdin/stdout. The transport type is inferred automatically when a command field is present.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"],
      "env": {
        "SOME_VAR": "value"
      }
    }
  }
}

Field	Required	Description
command	✅	Executable to run (e.g. npx, node, python3)
args	❌	Array of arguments passed to the command
env	❌	Extra environment variables merged into the process environment

Note: The process inherits PATH and NODE_PATH from the shell environment that started AnythingLLM. If a command such as npx is not found, ensure it is available in that shell's PATH.

---

sse — Server-Sent Events (legacy)

Connects to a remote MCP server using the legacy SSE transport. The type is inferred automatically when only a url field is present (no command), or when "type": "sse" is set explicitly.

{
  "mcpServers": {
    "my-sse-server": {
      "url": "https://example.com/mcp",
      "type": "sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

---

streamable / http — Streamable HTTP

Connects to a remote MCP server using the newer Streamable HTTP transport.

{
  "mcpServers": {
    "my-http-server": {
      "url": "https://example.com/mcp",
      "type": "streamable",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Both "type": "streamable" and "type": "http" select this transport.

Field	Required	Description
url	✅	Full URL of the MCP endpoint
type	✅	"sse", "streamable", or "http"
headers	❌	HTTP headers sent with every request (useful for auth)

---

AnythingLLM-Specific Options

An optional anythingllm block inside any server definition can control AnythingLLM-specific behaviour:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "anythingllm": {
        "autoStart": false
      }
    }
  }
}

Option	Type	Default	Description
autoStart	boolean	true	When false, the server is skipped at startup and must be started manually from the Admin UI

---

Full Example

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "remote-tools": {
      "url": "https://mcp.example.com/mcp",
      "type": "streamable",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    },
    "optional-server": {
      "command": "node",
      "args": ["/opt/mcp/server.js"],
      "anythingllm": {
        "autoStart": false
      }
    }
  }
}

---

Managing Servers via the Admin UI

MCP servers can be managed without editing the JSON file directly:

1. Log in as an Admin.
2. Go to Admin → Agents → MCP Servers.
3. From this page you can:
   • View all configured servers and the tools each one exposes.
   • Start or stop individual servers.
   • Delete a server (removes it from the JSON file).
   • Force-reload all servers (stops all, re-reads the file, restarts them).

Any changes made through the UI are persisted back to anythingllm_mcp_servers.json.

---

How Servers Are Started

• At startup, MCPHypervisor reads the config file and starts all servers whose anythingllm.autoStart is not false.
• Each server has a 30-second connection timeout. If a server fails to connect within that window it is marked as failed and its process is cleaned up.
• Servers are exposed to agents via the @agent directive using the naming convention @@mcp_<server-name>.

---

Troubleshooting

Symptom	Likely Cause	Fix
ENOENT / command not found	The executable is not in PATH	Use the full absolute path for command, or ensure the binary is accessible in the shell that starts AnythingLLM
Connection timeout after 30 s	Server process started but did not respond	Check the server's own logs; verify arguments are correct
Tools not visible to agent	Server failed to start	Check the status badge in Admin → Agents → MCP Servers for the error message
Auth / 401 errors on remote servers	Missing or incorrect credentials	Verify headers or env values in the config

---

Further Reading

• AnythingLLM MCP Compatibility Docs
• Model Context Protocol Specification