MCP servers interfaced through skills – thoughts?

Keen now integrates Model Context Protocol (MCP) servers through its existing Skills system, generating an ordinary skill directory under `~/.keen/skills` for each connected server so the LLM discovers MCP tools before calling the shared `call_mcp_tool` tool. For a server named `github`, Keen writes `SKILL.md`, a `.keen-generated-mcp.json` metadata file, and one schema file per tool under `schemas/`, capping the generated tool table at 1000 rows and rejecting tool names that attempt path traversal; the system prompt lists only a concise skill entry, with detailed tool lists and schemas loaded on demand.

MCP Servers Driven by Skills ¶ mcp-servers-driven-by-skills Keen integrates MCP servers through the existing Skills system. Connected MCP servers generate ordinary skill directories under ~/.keen/skills , and the LLM uses those skill files to discover MCP tools before calling the shared call mcp tool tool. Overview ¶ overview The flow is: 1. User configures MCP servers in ~/.keen/mcp/configs.json , or a file selected with --mcp-config <file path see configuration location mcp-servers.html configuration-location . 2. Keen starts the MCP manager and connects to configured servers. 3. For each connected server, Keen lists MCP tools. 4. Keen generates a skill named mcp:<server . 5. The generated skill appears in the skills catalog sent in the system prompt. 6. When the LLM needs that server, it reads the generated SKILL.md and relevant schema file. 7. The LLM calls the built-in call mcp tool tool with the configured server name, tool name, and schema-shaped arguments. This makes MCP discovery prompt-efficient: the system prompt only lists a concise skill entry, while detailed tool lists and schemas are loaded on demand. Generated skill layout ¶ generated-skill-layout For a configured server named github , Keen generates: ~/.keen/skills/mcp:github/ ├── SKILL.md ├── .keen-generated-mcp.json └── schemas/ ├── create issue.json └── list issues.json The skill name is always: mcp:<server For example: | MCP server | Generated skill | |---|---| | github | mcp:github | | context7 | mcp:context7 | | posthog | mcp:posthog | How MCP skills are generated ¶ how-mcp-skills-are-generated Keen generates MCP skills from connected server tool metadata: - SKILL.md contains YAML frontmatter and a markdown table of available tools. - One schema file is written for each tool's MCP input schema. - Tool schemas are written to schemas/<tool-name .json . - If a tool has no input schema, Keen writes an empty JSON object. - Generation is atomic: Keen writes to a temporary directory, then replaces the target skill directory. - Tool names that attempt path traversal are rejected. - The generated tool table is capped at 1000 rows. - Long descriptions are truncated. Example generated SKILL.md : --- name: mcp:github description: Use this skill to interact with the github MCP server. --- Available tools | Tool | Description | |------|-------------| | create issue | Create a GitHub issue | | list issues | List issues | The generated metadata file looks like: { "managed by": "keen-mcp", "server": "github", "status": "connected", "tool count": 2, "last successful refresh": "2026-05-21T12:00:00Z", "last error": "" } Schema generation ¶ schema-generation Each MCP tool's InputSchema becomes a JSON file in the generated skill directory. For a tool named create issue , the schema path is: ~/.keen/skills/mcp:github/schemas/create issue.json For nested tool names, directories may be created under schemas/ as long as the name does not escape the schemas directory. The LLM is instructed by call mcp tool to read: 1. ~/.keen/skills/mcp:<server /SKILL.md 2. ~/.keen/skills/mcp:<server /schemas/<tool .json Then it must pass arguments matching the schema exactly. How the LLM uses MCP skills ¶ how-the-llm-uses-mcp-skills Keen includes enabled skills in the system prompt as a catalog entry like: - mcp:github: Use this skill to interact with the github MCP server. → read ~/.keen/skills/mcp:github/SKILL.md When the user asks for something that needs the MCP server, the LLM follows the same skill activation process as regular skills: 1. Read the generated SKILL.md to discover available tools. 2. Pick the relevant MCP tool. 3. Read that tool's schema file. 4. Call call mcp tool . ⚠️ There is a persistence difference between explicit slash activation and LLM-driven skill reading: Slash activation /mcp:<server ... is handled before the LLM turn. Keen reads SKILL.md , applies slash-command argument substitution, and injects the processed skill body as an Activate skill: ... conversation message. Because it is a message, it remains in retained conversation history after the turn finishes. LLM-driven activation happens when the model reads ~/.keen/skills/mcp:<server /SKILL.md itself after seeing the skill catalog entry. No slash-command argument substitution is applied. The skill body arrives as a tool result for the active turn, and raw tool traffic is compacted when the turn finishes, so a later turn may need to read the skill file again. For context management , prefer letting the LLM read SKILL.md on demand instead of explicitly injecting MCP skills with a slash command. This keeps detailed skill instructions out of retained conversation history unless they are needed again. Example call mcp tool input: { "server": "github", "tool": "create issue", "arguments": { "title": "Fix flaky test", "body": "The race test fails intermittently." } } The call mcp tool tool is generic. It does not expose one separate LLM tool per MCP server tool. The generated skill and schema files provide the discovery and argument contract. Benefits of the skill-driven approach ¶ benefits-of-the-skill-driven-approach | Benefit | Why it matters | |---|---| | Smaller system prompt | The prompt includes only a skill catalog entry, not every MCP tool schema. | | On-demand context | The LLM reads only the MCP server and schema it needs. | | Works with existing skill UX | MCP servers appear in /skills list , can be enabled/disabled, and are activated like other skills. | | Stable tool surface | Keen only needs one built-in LLM tool: call mcp tool . | | Dynamic server discovery | Generated skill files reflect the server's live tool list after successful startup or refresh. | | Clear audit point | User approval happens for each call mcp tool execution. | | Failure isolation in prompt | Failed MCP servers are disabled as skills, keeping unavailable tools out of the skill catalog. | Startup synchronization ¶ startup-synchronization After MCP startup completes, the REPL syncs MCP statuses with skills: | MCP state | Skill behavior | |---|---| | connected | Generate/refresh mcp:<server skill, mark it enabled, then reload skills. | | disconnected | Mark mcp:<server disabled, then reload skills. | | auth required | Mark mcp:<server disabled, show a connect hint. | | auth failed | Mark mcp:<server disabled, show a connect hint. | | Removed from MCP config | If a previously enabled mcp:<server skill is not in the configured server set, mark it disabled. | Generated files for failed or removed servers are not necessarily deleted. Instead, Keen disables the skill so it is hidden from the enabled skills catalog. Manual refresh and authentication ¶ manual-refresh-and-authentication Use: /mcp connect <server This calls MCP Refresh for the server. For OAuth servers, /mcp connect also: - uses the browser OAuth code fetcher, - uses http://localhost:1456/auth/mcp/callback as the redirect URL, - forces re-authentication by clearing the stored token first, - waits up to 5 minutes for connection/authentication. On success: 1. Keen refreshes the server's MCP tools. 2. Keen regenerates the mcp:<server skill. 3. Keen enables the skill. 4. Keen reloads skills so the LLM sees the skill catalog entry. On failure: 1. Keen reports the connection error. 2. Keen disables mcp:<server . 3. Keen reloads skills so the unavailable server is removed from the enabled skills catalog. Enabling and disabling MCP server skills ¶ enabling-and-disabling-mcp-server-skills MCP skills use the normal skills config file: ~/.keen/skills/config.json Example: { "is enabled": { "mcp:github": true, "mcp:posthog": false } } You can manage them with normal skill commands: /skills list /skills disable mcp:github /skills enable mcp:github /skills reload Important behavior: - Skills default to enabled if they are not present in config.json . - A connected MCP server refreshes its generated skill files during startup MCP sync, but it does not override an explicitly disabled skill. - Running /mcp connect <server successfully refreshes the generated skill files and enables the skill. - A failed MCP server is automatically disabled during MCP sync. - A stale MCP skill whose server was removed from MCP config is removed from skills config and its generated skill directory is deleted during MCP sync. - Disabling a generated MCP skill hides it from the skills catalog, but it does not remove the MCP server from the selected MCP configuration file and does not stop an already-running MCP session. To fully remove a server from Keen's MCP runtime, remove it from the selected MCP configuration file ~/.keen/mcp/configs.json by default, or the file passed to --mcp-config and restart Keen. What happens when MCP fails ¶ what-happens-when-mcp-fails | Scenario | Skill outcome | LLM outcome | |---|---|---| | Server connects and tools list succeeds on startup | Skill files are generated or refreshed; existing enabled/disabled preference is preserved. | LLM can discover the skill only when it is enabled, but connected MCP tools remain callable through call mcp tool . | | Server fails to connect | Skill is disabled. | LLM does not see the skill in the enabled catalog. | | OAuth is required | Skill is disabled and Keen suggests /mcp connect <server . | LLM does not see the skill until auth succeeds. | | OAuth/API key auth fails | Skill is disabled. | LLM does not see the skill until the server reconnects. | | Tool listing fails | Skill generation is skipped; server state becomes failed. | Existing generated files may remain, but sync disables the skill for failure states. | | /mcp connect <server succeeds | Skill files are generated or refreshed, and the skill is enabled. | LLM can discover the skill in future turns. | | Server is removed from config | Any explicit skill status is removed from skills config and generated skill files are deleted on next startup sync. | LLM no longer sees the generated skill. | | MCP manager cannot start due invalid config | No MCP runtime is registered and call mcp tool is unavailable. | LLM cannot call MCP tools. Previously generated skills may still exist on disk, but they are only useful if enabled and the tool exists; fix config and restart. | Security and permissions ¶ security-and-permissions MCP tools can perform arbitrary actions depending on the remote server. Keen adds these guardrails: - Every call mcp tool request asks the user for approval. - The approval prompt includes the server, tool, and JSON arguments. - API keys are redacted from MCP errors/logs when possible. - Stdio credentials should be provided via environment variables in MCP config or the parent environment. - Generated schemas are local files under ~/.keen/skills/mcp:<server /schemas . Implementation references ¶ implementation-references | Concern | Code | |---|---| | MCP config format and validation | internal/mcp/config.go | | MCP runtime, connection, tool listing, tool calls | internal/mcp/manager.go | | OAuth handling and token persistence | internal/mcp/oauth.go | | Generated MCP skills and schemas | internal/mcpskills/mcpskills.go | | Startup MCP/skill synchronization | internal/cli/repl/repl helpers.go | | /mcp commands | internal/cli/repl/command handlers.go | | Generic LLM MCP tool | internal/tools/call mcp tool.go | | Skills config and catalog | internal/skills/config.go , internal/skills/discover.go |