Runtimes

How Skilder runtimes execute MCP servers and route tool calls between agents and tools across different deployment modes.

A runtime manages MCP server processes and routes tool calls between agents and the tools those servers provide.

Two processes, not one

Skilder's execution plane is two separate services. They were one image until the runtime/MCP split; they scale differently, so they ship apart.

	Remote MCP server	Runtime
Package / image	`@skilder-ai/remote-mcp`	`@skilder-ai/runtime`
Serves	`/mcp` (Streamable HTTP), `/health`, `/ready`, OAuth resource metadata	`/health`, `/ready`
Default port	3001	3003
Configured with	`SYSTEM_KEY` only	`RUNTIME_KEY`, or `SYSTEM_KEY` + `RUNTIME_NAME`
Does	Terminates agent HTTP and OAuth, holds MCP sessions, fans tool calls out over NATS	Spawns MCP server processes, runs skill scripts, holds upstream OAuth tokens

Agents connect to the remote MCP server. It never executes anything itself: every tool call and script leaves it as a NATS request to the runtime that owns the target, and the result comes back the same way. A runtime is never addressed over HTTP by an agent.

# The public MCP surface
SYSTEM_KEY=SYK_your_key REMOTE_PORT=3001 NATS_SERVERS=nats://... node dist/index.js

# A runtime that executes for it
RUNTIME_KEY=RTK_your_key REMOTE_PORT=3003 NATS_SERVERS=nats://... \
  PRIVATE_MCP_URL=http://remote-mcp:3001/mcp node dist/index.js

REMOTE_PORT starts a web service on both, serving GET /health (liveness — always 200 once the process is serving) and GET /ready (readiness — 200 only when the process is connected and authenticated). Point healthchecks at /health; use /ready to gate traffic. Container images default the port, so both are healthcheckable out of the box.

Connecting a local agent by spawning a runtime over stdio (USER_KEY) is no longer supported — connect every agent to the hosted Streamable HTTP endpoint instead (see Connect Your Agent).

A runtime given MCP_REMOTE_ENABLED refuses to start. The fused mode is gone, and failing loudly beats leaving you to discover that nothing is serving :3001/mcp.

What the Runtime Does

Process lifecycle — Starts, monitors, and stops MCP server processes as needed. Supports lazy-start with idle timeout.
Environment variables and secrets — Injects configuration and credentials into each server at startup.
Tool call routing — Receives requests from NATS (or HTTP), forwards to the correct MCP server, returns results.
Isolation — Each MCP server runs in its own process.
OAuth token provisioning — Transparently provides OAuth tokens to MCP servers that need them.
Asset caching — Resolves @skilder-asset:/ paths to local cached files for cross-tool asset sharing.

MCP Server Status

Status	Meaning
Connected	Healthy, tools available
Starting	Initializing, wait and refresh
Pending	Being set up
Idle	Stopped due to inactivity, will restart on next tool call
Error	Something failed — check error details
Disconnected	Stopped, try restart

Supported Transports

Agents connect to Skilder over Streamable HTTP — the modern HTTP-based MCP transport used by Claude, ChatGPT, Copilot, Cursor, and every other current MCP client. (The stdio and SSE agent transports were removed.)

On the tool side, the runtime itself connects to the MCP servers you install using whichever transport each server declares (local stdio processes or remote streamable servers).

Benefits

Zero setup — MCP servers run as soon as you install them. No manual process management.
Managed uptime — The runtime handles process health, restarts, and resource allocation.
Consistent environment — Standardized runtime eliminates configuration drift.

Environment Variables

MCP servers need credentials or config to connect to external services. Configure these as environment variables when installing or editing a server. The runtime injects them at startup. Sensitive values are stored securely and never exposed after initial entry.

See Configuration for the full list of runtime environment variables.