docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
207
docs/anythingllm_mcp.md
Normal file
207
docs/anythingllm_mcp.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# AnythingLLM MCP Server Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
AnythingLLM supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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](https://docs.anythingllm.com/mcp-compatibility/overview)
|
||||
- [Model Context Protocol Specification](https://modelcontextprotocol.io)
|
||||
Reference in New Issue
Block a user