Skip to content

mcp.md

Latest commit

 

History

History
141 lines (105 loc) · 4.63 KB

mcp.md

File metadata and controls

141 lines (105 loc) · 4.63 KB
Raw

agentctl mcp — Agent-callable AgentWorkload API

agentctl mcp serve exposes six Model Context Protocol tools that map 1:1 to AgentWorkload CRD verbs. External orchestrator agents (Claude Desktop, Cursor, ChatGPT, custom) can call these tools to provision their own Clawdlinux execution environments without a human running kubectl.

Why this exists

A Clawdlinux AgentWorkload is already an agent-readable interface — agents can read the schema and reason about the spec. What was missing was the wire protocol so an external agent can actually POST a workload into the cluster. agentctl mcp serve is that wire protocol. See issue #140.

Tools

Tool What it does Required args
create_workload Provision a new AgentWorkload. Returns UID + Pending phase. name, objective
get_workload_status Poll .status.phase + workflow steps. name
list_workloads List workloads (all namespaces if omitted). —
get_workload_logs Tail logs from the runtime pod. name
get_workload_cost Per-workload tokens + USD (today + MTD). name
delete_workload Delete (idempotent — deleted=false if not found). name

Full JSON schemas are returned by GET /tools — that is the only source of truth a client needs.

Quick start

# 1. Set a bearer token (any opaque string)
export CLAWDLINUX_MCP_TOKEN=$(uuidgen)

# 2. Boot the server (uses your KUBECONFIG context)
agentctl mcp serve --addr :8765 --default-namespace agentic-system

# 3. From another terminal — discover tools
curl -H "Authorization: Bearer $CLAWDLINUX_MCP_TOKEN" http://127.0.0.1:8765/tools | jq

# 4. Create a workload
curl -H "Authorization: Bearer $CLAWDLINUX_MCP_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST http://127.0.0.1:8765/call_tool \
     -d '{"tool":"create_workload","params":{
           "name":"demo-1",
           "objective":"Summarize today\'s arxiv RAG papers",
           "agents":["researcher","synthesizer"]
         }}' | jq

Verify with kubectl:

kubectl get agentworkloads -n agentic-system
# NAME      AGE
# demo-1    7s

Auth

agentctl mcp serve enforces Authorization: Bearer <token> when CLAWDLINUX_MCP_TOKEN (or --auth-token) is non-empty. An unset token disables auth entirely — only do this for local stdio transport on a trusted host.

Full RBAC integration (OIDC / SPIFFE) is tracked for v0.5; bearer-token is the minimum viable surface for the Phase 2 demo.

Transports

HTTP (default)

GET  /tools         → tool descriptors with JSON-Schema input definitions
POST /call_tool     → ToolRequest body, ToolResponse body
GET  /healthz       → 200 OK

ToolRequest:

{ "tool": "create_workload", "params": { "name": "demo-1", "objective": "..." } }

ToolResponse:

{ "tool": "create_workload", "success": true, "result": { "uid": "...", "phase": "Pending" } }

On failure: success=false and error is set; the body is always valid JSON, never an HTML error page.

stdio

agentctl mcp serve --transport stdio

Newline-delimited JSON. Each line on stdin is a ToolRequest; each line on stdout is a ToolResponse. The list_tools pseudo-tool returns the schema. Designed for Claude Desktop and Cursor MCP client configs.

In-cluster vs out-of-cluster

agentctl mcp serve uses standard kubeconfig resolution — --kubeconfig, then $KUBECONFIG, then ~/.kube/config, then in-cluster ServiceAccount.

For production, run it as a Deployment in agentic-system with a Role/RoleBinding that grants:

- apiGroups: ["agentic.clawdlinux.org"]
  resources: ["agentworkloads"]
  verbs: ["get", "list", "create", "delete"]
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list"]

…and never grant cluster-admin. The MCP server is a privileged surface — treat it like an admission webhook.

Examples

Out of scope (this sprint)

  • gRPC transport — HTTP and stdio only.
  • WebSocket streaming.
  • Full RBAC integration (OIDC / SPIFFE) — bearer token only; deferred to v0.5.
  • MCP JSON-RPC 2.0 framing for non-stdio transports — the HTTP envelope is a simpler shape that is easier to demo. Tracked for v0.5 alongside the SDK alignment work.