MCP Overview

Model Context Protocol (MCP) is an open standard that allows AI agents to call tools exposed by external processes or HTTP services. Scarab-Runtime's Phase 8.1 integration lets operators register MCP servers once and attach them to any running agent on demand.

How it works

MCP architecture

When an MCP server is attached to an agent, agentd:

  1. Spawns (Stdio) or connects to (HTTP) the server.
  2. Performs the JSON-RPC 2.0 initialize → notifications/initialized → tools/list handshake.
  3. Registers each discovered tool in the agent's ToolRegistry under the namespace mcp.<server-name>.<tool-name>.
  4. The agent can immediately invoke those tools via tool.invoke:mcp.<server-name>.*.

When the server is detached, all namespaced tools are removed and the connection is closed cleanly (shutdown + exit for Stdio; connection close for HTTP).

Transports

TransportDescription
stdioagentd spawns a subprocess and communicates over its stdin/stdout
httpagentd POSTs JSON-RPC messages to <base_url>/message

Tool naming

Every MCP tool is namespaced to avoid collisions:

mcp.<server-name>.<original-tool-name>

Example: a server named github exposing list_prs becomes mcp.github.list_prs.

An agent must declare tool.invoke:mcp.github.* (or a more specific capability) to call those tools.

Credential handling

MCP server definitions may include environment variable templates that reference secrets via the {{secret:<name>}} handle syntax. The daemon resolves these handles at attach time; the plaintext value is passed to the subprocess environment but is never stored in the database or returned over IPC.

Lifecycle

MCP server lifecycle

A server definition can be attached to multiple agents simultaneously; each attachment gets its own McpSession.

Manifest auto-attach

MCP servers listed in a manifest's mcp_servers field are automatically attached when the agent spawns. See Manifest Auto-Attach.

Next steps