K kynetra.dev / KynML
Docs MCP Integration

MCP Integration

Run kynml.mcp.server to expose three KynML tools over MCP stdio:

  • kynml_validate(spec_text) validates an in-memory specification.
  • kynml_compile(spec_text) emits a PyTorch program without executing it.
  • kynml_train(path, tenant_id, job_id, approval_token) executes one approved job.

KynML deliberately does not expose a generic checkpoint-loading prediction
tool. Exact inference belongs in the generated Python service; Kynetra FX can
proxy that service for applications.

Install and start

pip install 'kynml[mcp]'
python -m kynml.mcp.server

Install kynml[mcp,train] only in a worker that will execute approved local
training. Validation and compilation do not need Torch.

Training safety boundary

kynml_train fails closed unless all execution settings are explicit:

export KYNML_MCP_WORKSPACE_ROOT=/absolute/path/to/approved/project
export KYNML_PRIME_APPROVAL_SECRET='<at-least-32-byte-shared-secret>'
export KYNML_MCP_EXECUTION_MODE=local-development
export KYNML_MCP_TIMEOUT_SECONDS=900
export KYNML_MCP_CPU_SECONDS=900
export KYNML_MCP_MEMORY_BYTES=8589934592
export KYNML_MCP_MAX_OUTPUT_BYTES=1048576

local-development runs a resource-limited child interpreter and is not a
production sandbox. Production must use isolated-worker plus an explicit
KYNML_MCP_WORKER_EXECUTABLE that enters the Deploy-owned container or OS
sandbox. The child gets no stdin, a minimal environment, a process session,
CPU/file/process limits, a timeout, and a combined stdout/stderr byte ceiling.
macOS cannot enforce RLIMIT_AS, so a container or VM must enforce memory.

Approval protocol kynetra.kynml.training-approval.v1 is HMAC-SHA256 over
canonical UTF-8 JSON. It binds the capability to:

  • expiry;
  • tenant ID and idempotent job ID;
  • normalized workspace-relative .kyn path;
  • exact SHA-256 of the approved source bytes.

Dispatch parses and compiles those immutable approved bytes. It rejects
imports, params, and sweeps until Prime can approve a versioned manifest for
the full source closure. Dataset, checkpoint, export, and run-manifest paths
must remain inside the configured workspace.

Before execution, KynML atomically records the tenant/job pair in
.kynml/mcp-job-claims.sqlite3 and denies reuse across server restarts that
share the workspace. A distributed production caller must additionally claim
the job globally in Prime/Kynetra DB, make retries idempotent, and refuse
parallel or terminal-state replay. The TypeScript signer/verifier contract
exists in Prime, but that global claim and Deploy handoff are not yet wired;
therefore production MCP training remains disabled. local-development is the
supported mode for direct testing.

Tool inputs

kynml_validate

{"spec_text": "model M:\n    input 1"}

Returns OK or a KynMLError report.

kynml_compile

{"spec_text": "model M:\n    input 1"}

Returns the generated Python source. In-memory compilation cannot resolve file
imports; use the CLI for composed projects.

kynml_train

{
  "path": "models/model.kyn",
  "tenant_id": "tenant-acme",
  "job_id": "job-train-001",
  "approval_token": "<short-lived Prime capability>"
}

Returns bounded stdout/stderr. Exceeding an execution or output limit kills the
whole worker process group and fails the request.

Client configuration

Use an absolute interpreter path so the MCP extra is available:

{
  "mcpServers": {
    "kynml": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "kynml.mcp.server"]
    }
  }
}

All tool exceptions are returned as ERROR: ... so a bad request does not end
the stdio session.

See also