From 3c074716202a4c109f4bcd340b734b82648bc7ad Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 7 Nov 2025 13:41:19 -0700 Subject: [PATCH] docs: Created docs that explain how to use MCP servers with Loki --- docs/function-calling/MCP-SERVERS.md | 121 +++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/function-calling/MCP-SERVERS.md diff --git a/docs/function-calling/MCP-SERVERS.md b/docs/function-calling/MCP-SERVERS.md new file mode 100644 index 0000000..393df12 --- /dev/null +++ b/docs/function-calling/MCP-SERVERS.md @@ -0,0 +1,121 @@ +# MCP Servers +[MCP servers](https://modelcontextprotocol.io/docs/getting-started/intro) are essentially APIs designed specifically for LLMs that work like a remote repository of +tools for the model to access and extend its capabilities. + +So think of it like this: Instead of having to write all your own custom tools to interact with different +services, those services can expose their functionality through an MCP server. + +Loki has first-class support for MCP servers. + +As mentioned in the [Loki Vault documentation](../VAULT.md), Loki can inject sensitive +configuration data into your MCP configuration file to ensure that secrets are not hard-coded. + +## Quick Links + +- [Important Note](#important-note) +- [MCP Server Configuration](#mcp-server-configuration) + - [Secret Injection](#secret-injection) +- [Default MCP Servers](#default-mcp-servers) +- [Loki Configuration](#loki-configuration) + - [Global Configuration](#global-configuration) + - [Role Configuration](#role-configuration) + - [Agent Configuration](#agent-configuration) + + +--- + +## Important Note +Be careful how many MCP servers you enable at one time, regardless of the context. When there is a significant +number of configured MCP servers, enabling too many MCP servers may overwhelm the context length of a model, +and quickly exceed token limits. + +## MCP Server Configuration +Loki stores the MCP server configuration file, `functions/mcp.json`, in the `functions` directory. You can find +this directory using the following command: + +```shell +loki --info | grep functions_dir | awk '{print $2}' +``` + +The syntax for the `functions/mcp.json` file is identical to the syntax for MCP server configurations for Claude Desktop. +So any time you're looking to add a new server, look at the docs for it and find the configuration example for +Claude desktop. You should be able to use the exact same configuration in your `functions/mcp.json` file. + +### Secret Injection +As mentioned in the [Loki Vault documentation](../VAULT.md), you can use Loki Vault to inject secrets into your MCP configuration file. + +In fact, this is why you need to set up your vault before using Loki at all: the built-in MCP configuration +requires you set up some secrets to use it. + +For more information about how to set up your vault and inject secrets, please refer to the [Loki Vault documentation](../VAULT.md). + +## Default MCP Servers +Loki ships with a `functions/mcp.json` file that includes some useful MCP servers: + +* [github](https://github.com/github/github-mcp-server) - Interact with GitHub repositories, issues, pull requests, and more. +* [docker](https://github.com/ckreiling/mcp-server-docker) - Manage your local Docker containers with natural language +* [slack](https://github.com/korotovsky/slack-mcp-server) - Interact with Slack + +## Loki Configuration +MCP servers, like tools, can be used in a handful of contexts: +* Inside a session +* Inside a role +* Inside an agent +* Globally (i.e. outside a session, role, or agent) + +Each of these has a different configuration and interaction with the global configuration. + +***Note:** The names of each MCP server referenced in the below configuration properties directly corresponds +to the names given in the `functions/mcp.json` configuration file. So if you change the name of an MCP server +from `slack` to `lucem-slack`, then you need to also update your Loki configuration accordingly. + +### Global Configuration +The global configuration is essentially what settings you want to have on by default when +you just invoke `loki`. (Don't worry about agents, roles, or sessions yet. We'll get to them in a bit). + +The following settings are available in the global configuration for MCP servers: + +```yaml +mcp_server_support: true # Enables or disables MCP server support (globally). +mapping_mcp_servers: # Alias for an MCP server or set of servers + git: github,gitmcp +enabled_mcp_servers: null # Which MCP servers to enable by default (e.g. 'github,slack') +``` + +A special note about `enabled_mcp_servers`: a user can set this to `all` to enable all configured MCP servers in the +`functions/mcp.json` configuration. However, **this should be used with caution**. When there is a significant number +of configured MCP servers, enabling all MCP servers may overwhelm the context length of a model, and quickly exceed +token limits. + +(See the [Configuration Example](../../config.example.yaml) file for an example global configuration with all options.) + +When running in REPL-mode, the `mcp_server_support` and `enabled_mcp_servers` settings can be overridden using the +`.set` command: + +![REPL set MCP servers](../images/mcp/global-settings-overrides-repl.png) + +### Role Configuration +When you create a role, you have the following MCP-related configuration options available to you: + +```yaml +enabled_mcp_servers: github # Which MCP servers the role uses. +``` + +The values for `mapping_mcp_servers` are inherited from the `[global configuration](#global-configuration)`. + +For more information about roles, refer to the [Roles](../ROLES.md) documentation. + +### Agent Configuration +When you create an agent, you have the following MCP-related configuration options available to you: + +```yaml +mcp_servers: # Which MCP servers the agent uses + - github + - docker +``` + +The values for `mapping_mcp_servers` are inherited from the [global configuration](#global-configuration). + +For more information about agents, refer to the [Agents](../AGENTS.md) documentation. + +For a full example configuration for an agent, see the [Agent Configuration Example](../../config.agent.example.yaml) file.