# 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)