MCP & Typed Tools
Skyflo uses the Model Context Protocol (MCP) to expose typed infrastructure tools to the Engine. Not prompt-hacking shell commands. Every tool has a defined schema, annotations that drive approval policy, and structured output.
What MCP Is
Model Context Protocol is an open standard for typed tool execution. Skyflo uses FastMCP to implement the MCP server. Tools are exposed with Pydantic-validated parameters and Field descriptions. The Engine discovers tools automatically and invokes them with schema-validated inputs.
Why Typed Tools Matter
Raw shell commands are brittle. Prompts that generate kubectl strings are unsafe. Typed tools provide:
- Schema validation: Parameters are validated before execution. Invalid inputs fail fast.
- Approval policy: Annotations (
readOnlyHint,destructiveHint) drive the Engine's approval gate. - Structured output: Tool results are typed. The model receives parseable data, not free-form text.
- Auditability: Every invocation is logged with exact parameters and results.
Tool Categories
| Category | Tag | Description |
|---|---|---|
| Kubernetes | k8s | Discovery, logs, exec, apply, diff, scale, rollout, drain |
| Helm | helm | Search, install, upgrade, rollback, list, status, template |
| Argo Rollouts | argo | Pause, resume, promote, abort, history, analysis runs |
| Jenkins | jenkins | Jobs, builds, logs, SCM, identity, trigger, stop |
| Memory | memory | Search, read, list, history, remember, patch, propose promotion |
On-Demand Loading
Tools are not loaded all at once. Sending every tool schema on every turn would consume ~8,000 tokens before the user message is even considered.
Instead, the Engine uses a virtual load_toolset tool. The LLM calls it when it determines a toolset is needed for the current request. The gate node handles it in-process (no MCP round-trip, no approval gate). The next model turn sees the expanded schema set.
Default context: Kubernetes read-only tools + memory read tools + load_toolset (~1,500 tokens total).
| Toolset | Default loaded |
|---|---|
k8s read-only | Yes |
| Memory read tools | Yes |
helm, argo, jenkins | No — loaded on-demand |
| Write tools for any toolset | No — requires include_write_tools=true |
See Context Management for examples and the full flow.
Tool Annotations
Each tool declares metadata that drives Engine behavior:
readOnlyHint:true= auto-execute without approval.false= requires explicit approval before execution.destructiveHint:true= flagged for extra caution (delete, drain, uninstall). Surfaces additional warnings in the UI.
These annotations are enforced by the Engine. The MCP server declares them. The Engine respects them. No override.
Safety defaults: missing metadata → requires approval. Metadata fetch error → requires approval. Fail-safe, not fail-open.
Transport
The Engine and MCP server communicate over streamable HTTP transport (StreamableHttpTransport). In-cluster deployment uses Kubernetes service DNS: http://skyflo-mcp:8888/mcp.
Tool discovery runs at startup. The ToolsCache holds schema definitions in memory to avoid repeated HTTP calls. Toolset filtering is applied per turn based on loaded_toolsets agent state.
Extensibility
New tools follow the same typed pattern. Register with @mcp.tool(). Define Pydantic models for parameters. Set readOnlyHint and destructiveHint appropriately. Community contributions are encouraged.
See the individual capability pages for details on each category: