Dark-Alex-17/coyote
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: Added documentation for the new MCP management CLI flags

Dark-Alex-17
2026-08-12 17:47:44 -06:00
parent 41d278de59
commit 48d42bec0b
2 changed files with 182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MCP-Servers.md
+178
@@ -36,6 +36,9 @@ OAuth-protected remote servers are supported natively (see [OAuth Authentication
Every server entry **must** include a `"type"` field set to one of: `"stdio"`, `"http"`, or `"sse"`.
> **Prefer the CLI over hand-editing?** Skip to [Managing MCP Servers from the CLI](#managing-mcp-servers-from-the-cli)
> for `--mcp-add`, `--mcp-list`, `--mcp-get`, and `--mcp-remove`.
> **Running inside a [Docker Sandbox](Sandboxes)?** MCP servers often need extra network allowances beyond what the base
> kit provides. See [Sandbox Compatibility](#sandbox-compatibility) at the bottom of this page for details and
> common gotchas.
@@ -350,6 +353,181 @@ 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 [Coyote Vault documentation](Vault).
# Managing MCP Servers from the CLI
Coyote provides CLI flags to add, list, inspect, and remove MCP servers without hand-editing `mcp.json`. The flag
surface mirrors [Claude Code's `claude mcp add`](https://docs.claude.com/en/docs/claude-code/mcp) so muscle memory
transfers over directly.
## Adding a server
### Stdio (local subprocess)
Use trailing `--` to separate Coyote's flags from the server command:
```shell
coyote --mcp-add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
```
With environment variables:
```shell
coyote --mcp-add github --env GITHUB_TOKEN={{GITHUB_TOKEN}} \
-- docker run -i --rm ghcr.io/github/github-mcp-server
```
`--env` is repeatable (`--env KEY1=VAL1 --env KEY2=VAL2`). Any value wrapped in `{{NAME}}` is treated as a
[Vault](Vault) reference: if the secret is not already stored, Coyote will prompt you to add it interactively
(see [Automatic secret provisioning](#automatic-secret-provisioning) below).
### HTTP (Streamable HTTP)
```shell
coyote --mcp-add notion --transport http --url https://mcp.notion.com/mcp
```
With headers for static-token authentication:
```shell
coyote --mcp-add datadog --transport http \
--url https://mcp.datadoghq.com/api/unstable/mcp-server/mcp \
--header "Authorization: Bearer {{DATADOG_TOKEN}}"
```
`--header` is repeatable. For OAuth-protected servers, use `--client-id`, `--callback-port`, and `--redirect-host`
(see [OAuth Authentication](#oauth-authentication) for background on when each is needed):
```shell
coyote --mcp-add slack --transport http --url https://mcp.slack.com/mcp \
--client-id 1601185624273.8899143856786 --callback-port 3118
```
### SSE (legacy HTTP+SSE)
```shell
coyote --mcp-add legacy --transport sse --url http://127.0.0.1:64342/sse
```
### Transport inference
You can usually omit `--transport`:
- If a trailing `--` command is present, the transport defaults to `stdio`.
- Otherwise it defaults to `http`.
Pass `--transport` explicitly when adding an `sse` server or when you want to be pedantic.
### Overwriting an existing server
By default, `--mcp-add` prompts before overwriting an entry with the same name. Pass `--mcp-force` to skip the prompt:
```shell
coyote --mcp-add github --mcp-force -- docker run -i --rm ghcr.io/github/github-mcp-server
```
## Listing servers
```shell
coyote --mcp-list
```
Prints every server from both user and workspace scopes, one line per server with its transport and target. Restrict
with `--scope`:
```shell
coyote --mcp-list --scope workspace
```
## Inspecting a server
```shell
coyote --mcp-get github
```
Prints the JSON block for the named server. Coyote searches user scope first, then workspace scope. Use `--scope` to
restrict:
```shell
coyote --mcp-get my-db --scope workspace
```
## Removing a server
```shell
coyote --mcp-remove github
```
Prompts before deleting. Skip the prompt with `--mcp-force`:
```shell
coyote --mcp-remove github --mcp-force
```
Coyote removes the server from the first scope it's found in (user first, then workspace). Use `--scope` to target
a specific file.
## Scope
The `--scope` flag controls which file `--mcp-add` / `--mcp-remove` / `--mcp-list` / `--mcp-get` read from or write
to:
| Value | File |
|-------------|-----------------------------------------------------------------------------------------------|
| `user` | `~/.config/coyote/functions/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
[Workspace-Local MCP Servers](#workspace-local-mcp-servers), and writes to `.coyote/mcp.json` when creating a new file.
## Automatic secret provisioning
Any string value passed to `--env`, `--header`, `--url`, `--client-id`, `--client-secret`, `--cwd`, or
`--redirect-host` is scanned for `{{NAME}}` [Vault](Vault) references. For each token whose secret isn't already
in your vault, Coyote will:
1. Print `Value references vault secret {{ NAME }} which is not stored yet.`
2. Prompt: `Add 'NAME' to the vault now?` (default: yes)
3. On confirmation, run the standard [vault add-secret](Vault) flow with masked input for the value
The literal `{{NAME}}` token is what gets written to `mcp.json`. Interpolation happens at load time. This means you
can safely commit a workspace `mcp.json` without exposing secret values.
If you decline a prompt, the add is aborted and no config changes are written.
## Flag reference
| Flag | Purpose |
|-----------------------------------|------------------------------------------------------------------------------------|
| `--mcp-add <NAME>` | Add a server |
| `--mcp-remove <NAME>` | Remove a server |
| `--mcp-list` | List all servers |
| `--mcp-get <NAME>` | Show one server's config as JSON |
| `--mcp-force` | Skip overwrite / removal confirmation |
| `--transport <stdio\|http\|sse>` | Explicit transport (inferred if omitted) |
| `--scope <user\|workspace>` | Config file to read/write (default: `user`) |
| `--url <URL>` | Endpoint for `http` / `sse` servers |
| `--env KEY=VALUE` | Env var for `stdio` (repeatable) |
| `--header "Name: Value"` | HTTP header for `http` / `sse` (repeatable) |
| `--cwd <PATH>` | Working directory for `stdio` |
| `--client-id <ID>` | OAuth client ID for `http` / `sse` |
| `--client-secret <SECRET>` | OAuth client secret (use `{{NAME}}` to reference a vault secret) |
| `--callback-port <PORT>` | OAuth callback port |
| `--redirect-host <HOST>` | OAuth redirect host (`127.0.0.1` by default) |
| `-- <cmd> [args...]` | Stdio command + args (everything after `--` is passed to the server verbatim) |
## Notes and caveats
- **`--mcp-list` / `--mcp-get` / `--mcp-remove` / `--mcp-add` are mutually exclusive.** Combining them in one
invocation is a parse error.
- **The trailing `-- <cmd>` is only meaningful for `--mcp-add` with `stdio` transport.** Passing it with `http` or
`sse` transport is an error.
- **Existing behavior change:** because Coyote now supports `--` as a trailing separator, prompt text that literally
starts with `-` needs to be quoted or preceded by `--`. This affects only unquoted hyphen-prefixed prompts, which
are rare in practice.
- **OAuth completion is separate from adding.** `--mcp-add` writes the config; you still need
`coyote --auth-mcp <NAME>` (or `.mcp auth <NAME>` in the REPL) to complete the OAuth authorization flow the first
time.
# Default MCP Servers
Coyote ships with a `functions/mcp.json` file that includes some useful MCP servers:
_Sidebar.md
+4
@@ -33,6 +33,10 @@
- [Custom Tools](Custom-Tools)
- [Custom Bash Tools](Custom-Bash-Tools)
- [MCP Servers](MCP-Servers)
- [Managing from CLI](MCP-Servers#managing-mcp-servers-from-the-cli)
- [Workspace-Local Servers](MCP-Servers#workspace-local-mcp-servers)
- [OAuth Authentication](MCP-Servers#oauth-authentication)
- [Sandbox Compatibility](MCP-Servers#sandbox-compatibility)
## Agents
- [Agents](Agents)