docs: Created docs that explain how to use MCP servers with Loki
This commit is contained in:
@@ -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
|
||||
<!--toc:start-->
|
||||
- [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)
|
||||
<!--toc:end-->
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
Reference in New Issue
Block a user