knosh list-mcp¶

List all MCP servers configured under mcp in knosh.json.

Synopsis¶

knosh list-mcp
knosh list-mcp --agent <id>

Description¶

list-mcp prints every MCP server configured under the mcp key in knosh.json, including disabled ones. It is useful for verifying that a local server's command or commandLine resolved the way you expect, or that a remote server's url and header count are what you intended.

This command only inspects configuration — it does not start, connect to, or otherwise contact any of the listed servers. To actually connect to one server and confirm it works, see mcp-info.

--agent¶

Resolves each server's effective enabled state for a specific agent, applying that agent's mcp: frontmatter overrides on top of the global enabled value.

If --agent is omitted, list-mcp falls back to the config's defaultAgentId, when one is set. If the default agent fails to load, list-mcp warns on stderr and falls back to the global-only view. An explicit --agent <id> that fails to load is a hard error. When no agent context is available (no --agent, no defaultAgentId, or no agents configured), the output shows only the global configuration.

Output¶

With no agent context, the output includes an entry for each configured server, sorted by name. A local server prints its command and environment count; a remote server prints its url and headers count instead:

## my-server
- command: bun x my-mcp
- type: local
- environment: 2 variable(s)
- timeout: 30s

## another-server (disabled)
- command: node ./server.js
- type: local
- environment: 0 variable(s)

## remote-server
- url: https://mcp.example.com/mcp
- type: remote
- headers: 1 header(s)
- timeout: 10s

• A server annotated (disabled) has enabled: false in its config; it is listed, not hidden.
• environment (local) and headers (remote) show only the count of configured environment variables or HTTP headers — never their names or values, since they commonly hold secrets.
• The timeout line appears only when the server sets a timeout.

With an agent context (explicit --agent or a resolved default agent), each entry also shows a status block distinguishing the global setting, the agent's effective setting, and whether an override applied:

## playwright

- command: bun x playwright-mcp
- type: local
- environment: 0 variable(s)
- status
    - global: enabled
    - agent 'reviewer': disabled (override)

A server whose agent-facing state matches the global value shows (inherited) instead of (override).