[WIP] webui: simple MCP (Model Context Protocol) support (tool calls)

common/arg.cpp

@@ -2697,6 +2697,21 @@ common_params_context common_params_parser_init(common_params & params, llama_ex
             params.ssl_file_cert = value;
         }
     ).set_examples({LLAMA_EXAMPLE_SERVER}).set_env("LLAMA_ARG_SSL_CERT_FILE"));
+    add_opt(common_arg(
+        {"--mcp-config"}, "FNAME",
+        "path to MCP server configuration JSON file",
+        [](common_params & params, const std::string & value) {
+            params.mcp_config = value;
+        }
+    ).set_examples({LLAMA_EXAMPLE_SERVER}).set_env("LLAMA_ARG_MCP_CONFIG"));
+    add_opt(common_arg(
+        {"--webui-mcp"},
+        {"--no-webui-mcp"},
+        "enable MCP/WebSocket support on HTTP_PORT + 1 (default: disabled)",
+        [](common_params & params, bool value) {
+            params.webui_mcp = value;
+        }
+    ).set_examples({LLAMA_EXAMPLE_SERVER}).set_env("LLAMA_ARG_WEBUI_MCP"));
     add_opt(common_arg(
         {"--chat-template-kwargs"}, "STRING",
         string_format("sets additional params for the json template parser"),

common/common.cpp

@@ -941,6 +941,62 @@ std::string fs_get_cache_file(const std::string & filename) {
     return cache_directory + filename;
 }
 
+std::string fs_get_config_directory() {
+    std::string config_directory = "";
+    auto ensure_trailing_slash = [](std::string p) {
+        if (p.back() != DIRECTORY_SEPARATOR) {
+            p += DIRECTORY_SEPARATOR;
+        }
+        return p;
+    };
+    if (getenv("LLAMA_CONFIG")) {
+        config_directory = std::getenv("LLAMA_CONFIG");
+    } else {
+#if defined(__linux__) || defined(__FreeBSD__) || defined(_AIX) || defined(__OpenBSD__)
+        if (std::getenv("XDG_CONFIG_HOME")) {
+            config_directory = std::getenv("XDG_CONFIG_HOME");
+        } else if (std::getenv("HOME")) {
+            config_directory = std::getenv("HOME") + std::string("/.config/");
+        } else {
+#if defined(__linux__)
+            struct passwd *pw = getpwuid(getuid());
+            if ((!pw) || (!pw->pw_dir)) {
+                throw std::runtime_error("Failed to find $HOME directory");
+            }
+            config_directory = std::string(pw->pw_dir) + std::string("/.config/");
+#else
+            throw std::runtime_error("Failed to find $HOME directory");
+#endif
+        }
+#elif defined(__APPLE__)
+        // Use ~/.llama.cpp/ for simplicity on macOS
+        config_directory = std::getenv("HOME") + std::string("/.llama.cpp");
+#elif defined(_WIN32)
+        config_directory = std::getenv("APPDATA");
+#elif defined(__EMSCRIPTEN__)
+        GGML_ABORT("not implemented on this platform");
+#else
+#  error Unknown architecture
+#endif
+        config_directory = ensure_trailing_slash(config_directory);
+#if !defined(__APPLE__)
+        // On macOS, we use ~/.llama.cpp/ directly (already includes llama.cpp)
+        config_directory += "llama.cpp";
+#endif
+    }
+    return ensure_trailing_slash(config_directory);
+}
+
+std::string fs_get_config_file(const std::string & filename) {
+    GGML_ASSERT(filename.find(DIRECTORY_SEPARATOR) == std::string::npos);
+    std::string config_directory = fs_get_config_directory();
+    const bool success = fs_create_directory_with_parents(config_directory);
+    if (!success) {
+        throw std::runtime_error("failed to create config directory: " + config_directory);
+    }
+    return config_directory + filename;
+}
+
 std::vector<common_file_info> fs_list(const std::string & path, bool include_directories) {
     std::vector<common_file_info> files;
     if (path.empty()) return files;

common/common.h

@@ -485,6 +485,10 @@ struct common_params {
 
     std::map<std::string, std::string> default_template_kwargs;
 
+    // MCP config
+    std::string mcp_config = "";                                                                           // NOLINT
+    bool webui_mcp = false;                                                                               // NOLINT
+
     // webui configs
     bool webui = true;
     std::string webui_config_json;
@@ -661,6 +665,9 @@ bool fs_is_directory(const std::string & path);
 std::string fs_get_cache_directory();
 std::string fs_get_cache_file(const std::string & filename);
 
+std::string fs_get_config_directory();
+std::string fs_get_config_file(const std::string & filename);
+
 struct common_file_info {
     std::string path;
     std::string name;

tools/server/CMakeLists.txt

@@ -38,6 +38,10 @@ set(TARGET_SRCS
     server-http.h
     server-models.cpp
     server-models.h
+    server-ws.cpp
+    server-ws.h
+    server-mcp-stdio.cpp
+    server-mcp-stdio.h
     server-task.cpp
     server-task.h
     server-queue.cpp
@@ -46,6 +50,8 @@ set(TARGET_SRCS
     server-common.h
     server-context.cpp
     server-context.h
+    # SHA1 for WebSocket handshake
+    ${CMAKE_SOURCE_DIR}/examples/gguf-hash/deps/sha1/sha1.c
 )
 set(PUBLIC_ASSETS
     index.html.gz
@@ -69,6 +75,7 @@ install(TARGETS ${TARGET} RUNTIME)
 
 target_include_directories(${TARGET} PRIVATE ../mtmd)
 target_include_directories(${TARGET} PRIVATE ${CMAKE_SOURCE_DIR})
+target_include_directories(${TARGET} PRIVATE ${CMAKE_SOURCE_DIR}/examples/gguf-hash/deps)
 target_link_libraries(${TARGET} PRIVATE server-context PUBLIC common cpp-httplib ${CMAKE_THREAD_LIBS_INIT})
 
 if (WIN32)

tools/server/README.md

@@ -1679,6 +1679,93 @@ Apart from error types supported by OAI, we also have custom types that are spec
 }
 ```
 
+### MCP (Model Context Protocol) Support
+
+The server supports [MCP](https://modelcontextprotocol.io/) for integrating external tools. MCP enables models to interact with external services like file systems, databases, APIs, and more.
+
+The server acts as an HTTP proxy for remote MCP servers, handling CORS for browser-based clients.
+
+#### MCP Configuration
+
+Create an MCP configuration file (JSON format) with remote MCP server URLs:
+
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "url": "http://127.0.0.1:38180/mcp",
+      "headers": {
+        "Authorization": "Bearer your-api-key"
+      }
+    },
+    "filesystem": {
+      "url": "http://127.0.0.1:38181/mcp"
+    }
+  }
+}
+```
+
+#### MCP Configuration Location
+
+The server looks for MCP configuration in the following order:
+1. `--mcp-config` command-line argument
+2. `LLAMA_MCP_CONFIG` environment variable
+3. `~/.llama.cpp/mcp.json` (Linux/macOS)
+4. `%APPDATA%/llama.cpp/mcp.json` (Windows)
+
+#### MCP Usage
+
+```bash
+# Enable MCP with --webui-mcp flag
+./llama-server -m model.gguf --webui-mcp
+
+# Specify config path
+./llama-server -m model.gguf --webui-mcp --mcp-config /path/to/mcp.json
+
+# Or use environment variable
+LLAMA_MCP_CONFIG=/path/to/mcp.json ./llama-server -m model.gguf --webui-mcp
+```
+
+#### MCP API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/mcp/servers` | GET | List available MCP server names from config |
+| `/mcp?server=<name>` | GET | Proxy GET requests to remote MCP server (SSE streams) |
+| `/mcp?server=<name>` | POST | Proxy POST requests to remote MCP server (JSON-RPC) |
+
+#### MCP Protocol
+
+The server proxies requests to remote MCP servers using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports). The web UI uses the official `@modelcontextprotocol/sdk` client.
+
+For more information about MCP, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).
+
+#### Example MCP Servers
+
+Here's how to run some example MCP servers that work with the default config:
+
+**Brave Search** (requires `BRAVE_API_KEY` environment variable - get one at https://brave.com/search/api/):
+
+```bash
+BRAVE_API_KEY=your-key-here npx -y @anthropic-ai/mcp-server-brave-search --transport http --port 38180
+```
+
+**Python interpreter** (with common data science packages):
+
+```bash
+uvx mcp-run-python --deps numpy,pandas,pydantic,requests,httpx,sympy,aiohttp streamable-http --port 38181
+```
+
+**Run both together** using `concurrently`:
+
+```bash
+BRAVE_API_KEY=your-key-here npx -y concurrently \
+  "npx -y @anthropic-ai/mcp-server-brave-search --transport http --port 38180" \
+  "uvx mcp-run-python --deps numpy,pandas,pydantic,requests,httpx,sympy,aiohttp streamable-http --port 38181"
+```
+
+Then update `mcp_config.example.json` with your settings and start llama-server with `--webui-mcp`.
+
 ### Legacy completion web UI
 
 A new chat-based UI has replaced the old completion-based since [this PR](https://github.com/ggml-org/llama.cpp/pull/10175). If you want to use the old completion, start the server with `--path ./tools/server/public_legacy`

tools/server/mcp_config.example.json

@@ -0,0 +1,41 @@
+{
+  "_comment": "Example MCP configuration for llama.cpp",
+  "_comment_location": "Configuration file locations (checked in order):",
+  "_comment_location_env": "  1. Path specified in LLAMA_MCP_CONFIG environment variable",
+  "_comment_location_unix": "  2. ~/.llama.cpp/mcp.json (macOS/Linux)",
+  "_comment_location_windows": "  3. %APPDATA%\\llama.cpp\\mcp.json (Windows)",
+  "_comment_types": "This file supports two types of MCP servers:",
+  "_comment_stdio": "  - Local stdio servers: spawned and managed by llama-server (using command, args, env)",
+  "_comment_remote": "  - Remote HTTP servers: proxied through llama-server with CORS support (using url, headers)",
+
+  "mcpServers": {
+    "_comment_section_stdio": "=== Local stdio servers (spawned by llama-server) ===",
+
+    "brave-search": {
+      "_comment": "Brave Search MCP server - provides web search capabilities",
+      "_comment_key": "Get your API key at https://brave.com/search/api/",
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/claude-code-mcp-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "..."
+      }
+    },
+
+    "python": {
+      "_comment": "Python execution MCP server - run Python code with common data science libraries",
+      "command": "uvx",
+      "args": ["mcp-run-python", "--deps", "numpy,pandas,pydantic,requests,httpx,sympy,aiohttp", "stdio"]
+    },
+
+    "_comment_section_remote": "=== Remote HTTP servers (proxied by llama-server) ===",
+
+    "remote-api": {
+      "_comment": "Example remote MCP server with authentication",
+      "_comment_usage": "The llama-server proxies requests to this URL and adds CORS headers",
+      "url": "http://127.0.0.1:38180/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN"
+      }
+    }
+  }
+}

tools/server/server-http.cpp

@@ -1,9 +1,11 @@
 #include "common.h"
 #include "server-http.h"
+#include "server-mcp.h"
 #include "server-common.h"
 
 #include <cpp-httplib/httplib.h>
 
+#include <algorithm>
 #include <functional>
 #include <string>
 #include <thread>
@@ -200,13 +202,24 @@ bool server_http_context::init(const common_params & params) {
     };
 
     // register server middlewares
-    srv->set_pre_routing_handler([middleware_validate_api_key, middleware_server_state](const httplib::Request & req, httplib::Response & res) {
-        res.set_header("Access-Control-Allow-Origin", req.get_header_value("Origin"));
+    srv->set_pre_routing_handler([middleware_validate_api_key, middleware_server_state, webui_mcp = params.webui_mcp](const httplib::Request & req, httplib::Response & res) {
+        // Get Origin header (browsers always send this)
+        std::string origin = req.get_header_value("Origin");
+        if (!origin.empty()) {
+            res.set_header("Access-Control-Allow-Origin", origin);
+        }
+
         // If this is OPTIONS request, skip validation because browsers don't include Authorization header
         if (req.method == "OPTIONS") {
             res.set_header("Access-Control-Allow-Credentials", "true");
             res.set_header("Access-Control-Allow-Methods",     "GET, POST");
-            res.set_header("Access-Control-Allow-Headers",     "*");
+            // Include MCP protocol headers for CORS only if MCP is enabled
+            if (webui_mcp) {
+                res.set_header("Access-Control-Allow-Headers",     "*, mcp-session-id, mcp-protocol-version");
+                res.set_header("Access-Control-Expose-Headers",    "mcp-session-id");
+            } else {
+                res.set_header("Access-Control-Allow-Headers",     "*");
+            }
             res.set_content("", "text/html"); // blank response, no data
             return httplib::Server::HandlerResponse::Handled; // skip further processing
         }
@@ -302,10 +315,14 @@ bool server_http_context::start() {
     return true;
 }
 
-void server_http_context::stop() const {
+void server_http_context::stop() {
     if (pimpl->srv) {
         pimpl->srv->stop();
     }
+    // Wait for server thread to finish
+    if (thread.joinable()) {
+        thread.join();
+    }
 }
 
 static void set_headers(httplib::Response & res, const std::map<std::string, std::string> & headers) {
@@ -398,3 +415,20 @@ void server_http_context::post(const std::string & path, const server_http_conte
     });
 }
 
+bool server_http_context::load_mcp_config(const std::string & config_path) {
+    try {
+        mcp_config = std::make_shared<llama_mcp_config>(config_path);
+        return true;
+    } catch (const std::exception & e) {
+        LOG_ERR("%s: failed to load MCP config: %s\n", __func__, e.what());
+        return false;
+    }
+}
+
+std::optional<mcp_server_config> server_http_context::get_mcp_server(const std::string & name) {
+    return mcp_config ? mcp_config->get_server(name) : std::nullopt;
+}
+
+std::vector<std::string> server_http_context::get_mcp_server_names() {
+    return mcp_config ? mcp_config->get_available_servers() : std::vector<std::string>{};
+}

tools/server/server-http.h

@@ -1,10 +1,15 @@
 #pragma once
 
+#include "server-mcp.h"
+
 #include <atomic>
 #include <functional>
 #include <map>
+#include <memory>
+#include <mutex>
 #include <string>
 #include <thread>
+#include <optional>
 
 struct common_params;
 
@@ -60,12 +65,23 @@ struct server_http_context {
     std::string hostname;
     int port;
 
+    // MCP configuration (for HTTP proxy)
+    std::shared_ptr<llama_mcp_config> mcp_config;
+
+    // Load MCP config from JSON file
+    bool load_mcp_config(const std::string & config_path);
+
+    // Get MCP server config by name
+    std::optional<mcp_server_config> get_mcp_server(const std::string & name);
+    // Get list of available MCP server names
+    std::vector<std::string> get_mcp_server_names();
+
     server_http_context();
     ~server_http_context();
 
     bool init(const common_params & params);
     bool start();
-    void stop() const;
+    void stop();
 
     // note: the handler should never throw exceptions
     using handler_t = std::function<server_http_res_ptr(const server_http_req & req)>;