From 13ef6b47392eb076c2f43e7b23d1c29d1d112432 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Tue, 25 Aug 2026 14:59:15 -0600 Subject: [PATCH] docs: updated the docs to reflect the new and preferred mcp.json file location --- Agents.md | 2 +- MCP-Servers.md | 31 +++++++++++++++++++------------ Skills.md | 2 +- Vault.md | 2 +- 4 files changed, 22 insertions(+), 15 deletions(-) diff --git a/Agents.md b/Agents.md index 3ed9448..70567ac 100644 --- a/Agents.md +++ b/Agents.md @@ -67,7 +67,7 @@ description: # Description of the agent, used in the UI version: 1 # Version of the agent # Function Calling Configuration mcp_servers: # Optional list of MCP servers that the agent utilizes - - github # Corresponds to the name of an MCP server in the `/functions/mcp.json` file + - github # Corresponds to the name of an MCP server in the `/mcp.json` file global_tools: # Optional list of additional global tools to enable for the agent; i.e. not tools specific to the agent - web_search - fs diff --git a/MCP-Servers.md b/MCP-Servers.md index dff4922..aaf2f14 100644 --- a/MCP-Servers.md +++ b/MCP-Servers.md @@ -17,18 +17,25 @@ number of configured MCP servers, enabling too many MCP servers may overwhelm th and quickly exceed token limits. # MCP Server Configuration -Coyote stores the MCP server configuration file, `functions/mcp.json`, in the `functions` directory. You can find -this directory using the following command: +Coyote stores the user-scope MCP server configuration file, `mcp.json`, directly in the Coyote configuration +directory (e.g. `~/.config/coyote/mcp.json` on Linux). You can find the resolved location of the file Coyote is +actually using with the following command: ```shell -coyote --info | grep functions_dir | awk '{print $2}' +coyote --info | grep mcp_config_file | awk '{print $2}' ``` -The syntax for the `functions/mcp.json` file matches [Claude Code's `.mcp.json` configuration format](https://docs.claude.com/en/docs/claude-code/mcp), +> [!NOTE] +> **Historical location:** older Coyote versions stored this file at `functions/mcp.json` inside the `functions` +> directory. That location is still fully supported: if `/mcp.json` does not exist but +> `/functions/mcp.json` does, Coyote keeps using the historical file. Existing installs continue to +> work unchanged, and there is no need to move the file. If both files exist, `/mcp.json` wins. + +The syntax for the `mcp.json` file matches [Claude Code's `.mcp.json` configuration format](https://docs.claude.com/en/docs/claude-code/mcp), with one small difference: the `type` field is **always required** in Coyote, even for stdio servers (Claude Code allows it to be omitted and infers `stdio` from the presence of a `command`). So any time you're looking to add a new server, look at its docs and find the Claude Code configuration example. You should be able to use the -exact same configuration in your `functions/mcp.json` file. Just make sure every entry has an explicit `type`. +exact same configuration in your `mcp.json` file. Just make sure every entry has an explicit `type`. **Note:** Coyote does not support Claude Code's `"streamable-http"` alias (use `"http"` instead) or `envFile`. For secrets, use [Coyote Vault](Vault) interpolation rather than Claude Code's `${VAR}` shell-style expansion. @@ -45,7 +52,7 @@ Every server entry **must** include a `"type"` field set to one of: `"stdio"`, ` ## Workspace-Local MCP Servers -In addition to the global `functions/mcp.json`, Coyote automatically loads a workspace-local MCP config at startup. +In addition to the global `mcp.json`, Coyote automatically loads a workspace-local MCP config at startup. This lets you ship project-specific MCP servers alongside your code without touching your global configuration. Coyote checks the following locations in order and loads the **first** file it finds: @@ -57,7 +64,7 @@ Coyote checks the following locations in order and loads the **first** file it f ``` / ├── .coyote/ -│ └── mcp.json # same format as functions/mcp.json (preferred) +│ └── mcp.json # same format as the global mcp.json (preferred) └── .mcp.json # Claude Code-compatible fallback ``` @@ -66,7 +73,7 @@ directory name is also customizable via the `COYOTE_WORKSPACE_CONFIG_DIR` [environment variable](Environment-Variables), so you can point Coyote at another tool's config directory (e.g. `.cursor/`, which holds an `mcp.json`) entirely. -The workspace file uses the exact same format as the global `functions/mcp.json`, including [Vault](Vault) secret +The workspace file uses the exact same format as the global `mcp.json`, including [Vault](Vault) secret interpolation via `{{SECRET_NAME}}` syntax. Workspace server names shadow global ones on collision. This means that if both files define a server named `my-db`, the workspace version takes precedence. @@ -473,7 +480,7 @@ to: | Value | File | |-------------|-----------------------------------------------------------------------------------------------| -| `user` | `~/.config/coyote/functions/mcp.json` (global; the default) | +| `user` | `~/.config/coyote/mcp.json` (global; the default) | | `workspace` | `.coyote/mcp.json` (project-local; created if missing) | For workspace scope, Coyote reads from the first existing file in the precedence order documented in @@ -529,7 +536,7 @@ If you decline a prompt, the add is aborted and no config changes are written. time. # Default MCP Servers -Coyote ships with a `functions/mcp.json` file that includes some useful MCP servers: +Coyote ships with an `mcp.json` file that includes some useful MCP servers: * [atlassian](https://github.com/atlassian/atlassian-mcp-server) - Interact with and manage Atlassian tools like Confluence and Jira. * [github](https://github.com/github/github-mcp-server) - Interact with GitHub repositories, issues, pull requests, and more. @@ -695,7 +702,7 @@ Enabling a server in any of these contexts exposes its capability-gated meta-fun [Interacting with MCP Servers](#interacting-with-mcp-servers) above. ***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 +to the names given in the `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 Coyote configuration accordingly. ## Global Configuration @@ -717,7 +724,7 @@ enabled_mcp_servers: null # Which MCP servers to enable by default. ``` A special note about `enabled_mcp_servers`: a user can set this to `all` (or include `all` in the list) to enable all -configured MCP servers in the `functions/mcp.json` configuration. +configured MCP servers in the `mcp.json` configuration. (See the [Configuration Example](https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml) file for an example global configuration with all options.) diff --git a/Skills.md b/Skills.md index c14fb4a..11d1da2 100644 --- a/Skills.md +++ b/Skills.md @@ -92,7 +92,7 @@ This is useful for project-specific workflows: a `db-migration` skill with your skill that loads the project's deployment MCP server, or any other task-specific overlay that doesn't belong in your global configuration. -Workspace skills can reference MCP servers from both the global `functions/mcp.json` and the workspace `.coyote/mcp.json` +Workspace skills can reference MCP servers from both the global `mcp.json` and the workspace `.coyote/mcp.json` (see [Workspace-Local MCP Servers](MCP-Servers#workspace-local-mcp-servers)). ## Frontmatter diff --git a/Vault.md b/Vault.md index 58570fb..1e958ad 100644 --- a/Vault.md +++ b/Vault.md @@ -211,7 +211,7 @@ At the time of writing, the following files support Coyote secret injection: | File Type | Description | Limitations | |-------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | `config.yaml` | The main Coyote configuration file | Cannot use secret injection on the `vault_password_file` field or anywhere inside the `secrets_provider` block | -| `functions/mcp.json` | The MCP server configuration file | | +| `mcp.json` | The MCP server configuration file | | | `/tools.` | Tool files for agents | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents)) |