<<<<<<< HEAD =======

>>>>>>> a6f660b (nav: update feature page links)

Protocols

MCP (Model Context Protocol) v2024-11-05 implementation in pure C — JSON-RPC 2.0 over stdio and streamable-http transports, 15 built-in tools, typed schemas, and platform-specific variants.

MCP

Protocol

2024-11-05

Spec Version

Built-in Tools

Transports

JSON-RPC 2.0

Wire Format

Overview
Transports
Message Types
Tool Registry
Tool Schemas
Server Implementations
Platform Variants

Overview

scorpiox code implements the Model Context Protocol (MCP) specification v2024-11-05 entirely in C. The protocol enables AI models to interact with local tools through a structured JSON-RPC 2.0 interface. The implementation supports both stdio and streamable-http transports, exposing 15 built-in tools across shell execution, filesystem, web, search, task management, scheduling, and event categories.

MCP Initialize Request

// Client → Server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "scorpiox-code",
      "version": "1.0.0"
    }
  }
}

MCP Initialize Response

// Server → Client
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "scorpiox-server",
      "version": "1.0.0"
    }
  }
}

Transports

Two transport mechanisms are supported. The stdio transport is used for local subprocess communication where the client spawns an MCP server process and communicates via stdin/stdout. The streamable-http transport is used for remote servers, sending JSON-RPC requests as HTTP POST to a /mcp endpoint.

stdio

Client spawns the MCP server as a subprocess. JSON-RPC messages are written to stdin and read from stdout, one JSON object per line. Used by scorpiox-mcp CLI.

local

streamable-http

Client sends HTTP POST requests to the server's /mcp endpoint. Each request body contains a single JSON-RPC message. Used by scorpiox-mcp-httpclient and scorpiox-server.

remote

stdio transport — scorpiox-mcp CLI

# Discover tools from an MCP server binary
$ scorpiox-mcp discover ./my-mcp-server

# Call a tool
$ scorpiox-mcp call ./my-mcp-server Bash '{"command": "echo hello"}'

# List available tools
$ scorpiox-mcp list ./my-mcp-server

streamable-http transport — HTTP client

# Connect to remote MCP server
$ scorpiox-mcp-httpclient --url https://mcp.example.com/mcp list

# Call a tool on a remote server
$ scorpiox-mcp-httpclient --url https://mcp.example.com/mcp \
    call WebSearch '{"query": "MCP protocol spec"}'

Message Types

The MCP protocol defines four message types for the session lifecycle and tool invocation. All messages follow the JSON-RPC 2.0 specification.

Method	Direction	Description
initialize	client → server	Initialize MCP session. Client sends capabilities and protocol version. Server responds with its capabilities, server info, and supported protocol version.
notifications/initialized	client → server	Client notification confirming initialization is complete. No response body required.
tools/list	client → server	List all available tools. Server responds with array of tool definitions including name, description, and input schema.
tools/call	client → server	Call a specific tool with parameters. Server executes the tool and returns the result as content array with text/image blocks.

tools/call — Execute a tool

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "Bash",
    "arguments": {
      "command": "uname -a",
      "timeout": 30000
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Linux scorpiox 6.1.0 #1 SMP x86_64 GNU/Linux"
      }
    ]
  }
}

Tool Registry

15 tools are registered in scorpiox/libsxutil/sx_tools.c using the SxToolDef struct. Each tool has a unique SxToolId enum value, an environment variable toggle, and a typed JSON input schema. Tool execution is handled by scorpiox/libsxnet/sx_agent.c. Additional MCP tools can be injected at runtime via sx_tools_set_extra_json().

Name	Category	Env Variable	Default	Description
Bash	shell	TOOL_BASH	Enabled	Execute a bash command
ReadImage	filesystem	TOOL_READIMAGE	Enabled	Read an image file and display it visually
ReadDocs	web	TOOL_READDOCS	Enabled	Fetch URL content as markdown using a headless browser
WebSearch	search	TOOL_WEBSEARCH	Enabled	Search the web using 11 engines concurrently
TaskManager	task-management	TOOL_TASKMANAGER	Enabled	Manage persistent tasks with create, add, complete, list
PlanMode	task-management	TOOL_PLANMODE	Enabled	Enter/exit plan mode for complex task breakdown
AskUserQuestion	interaction	TOOL_ASKUSERQUESTION	Enabled	Ask user interactive multiple-choice questions
InvokeSkill	skills	TOOL_INVOKESKILL	Enabled	Invoke or load a skill by name
BackgroundBash	shell	TOOL_BACKGROUNDBASH	Enabled	Execute a bash command in background
ReadBgOutput	shell	TOOL_READBGOUTPUT	Enabled	Read new output from a background task
ListBgTasks	shell	TOOL_LISTBGTASKS	Enabled	List all background tasks with status
KillBgTask	shell	TOOL_KILLBGTASK	Enabled	Kill a running background task by ID
SetCallback	scheduling	TOOL_SETCALLBACK	Enabled	Manage scheduled callback messages
EmitEvent	events	TOOL_EMITEVENT	Disabled	Emit structured events (disabled by default)
CreateFile	filesystem	TOOL_CREATEFILE	Enabled	Create a new file with specified content

Tool Schemas

Each tool defines a typed JSON Schema for its input parameters. Required parameters are validated before execution. The schema is served via tools/list so clients can build UIs and validate inputs.

Bash

command string required The bash command to execute

timeout integer Timeout in milliseconds (default: 120000)

ReadImage

file_path string required The absolute path to the image file

ReadDocs

url string required The URL to fetch

format string Output format: text, html, or markdown (default: markdown)

wait_ms integer Wait time for page load in ms (default: 3000)

WebSearch

query string required The search query

TaskManager

action string required Action: create, add, complete, list, pending, switch

query string required The search query

task_id integer Task ID (for add/complete)

text string Task name (create) or step text (add)

step_id integer Step ID (for complete)

BackgroundBash

command string required The bash command to execute in background

SetCallback

action string required Action: set, list, cancel

message string The message to send back after the delay

delay_seconds integer Seconds to wait before sending, 1-3600

repeat_count integer Number of times to fire (default: 20, -1 for infinite)

callback_id integer Callback slot ID to cancel

CreateFile

file_path string required The path for the new file to create (must not exist)

content string required The file content to write

Server Implementations

Three C source files implement the MCP protocol — two clients and one server. Each handles the full JSON-RPC 2.0 lifecycle including initialization, capability negotiation, and tool dispatch.

scorpiox-mcp.c

MCP client CLI that speaks JSON-RPC 2.0 over stdio to MCP server subprocesses. Supports discover, call, list, info, and test commands.

client stdio

scorpiox-mcp-httpclient.c

MCP client over Streamable HTTP. Connects to remote MCP servers via POST requests to /mcp endpoint.

client streamable-http

scorpiox-server.c

MCP server exposing tools via POST /mcp endpoint. Implements initialize, tools/list, and tools/call handlers with JSON-RPC 2.0.

server streamable-http

Internal C Architecture

// Tool registration in sx_tools.c
typedef struct {
    const char   *name;         // "Bash", "ReadDocs", ...
    const char   *description;  // tool description
    const char   *env_name;     // "TOOL_BASH" toggle
    bool          default_on;   // enabled by default?
    SxToolParam  *params;       // input schema
    int           param_count;
} SxToolDef;

// Tool execution in sx_agent.c
int sx_agent_handle_tool_call(
    const char *tool_name,
    cJSON      *arguments,
    cJSON      **result
);

Platform Variants

Tool availability and behavior varies across platforms. Windows adds a shell parameter to Bash and BackgroundBash tools for PowerShell/cmd selection. The WASM build disables tools that require fork/exec/pthread.

Windows

Bash and BackgroundBash gain an extra shell parameter. Accepted values: powershell (default) or cmd. All other tools remain unchanged.

15 tools

WASM

Single-threaded environment. Disabled tools: Bash, BackgroundBash, ReadBgOutput, ListBgTasks, KillBgTask, InvokeSkill. Tools requiring fork/exec/pthread are unavailable.

9 tools

Linux / macOS

Full tool support with native process management. All 15 tools enabled by default. macOS uses the same binary with ARM64 and x86_64 builds.

15 tools

Windows platform variant — extra shell parameter

// Windows Bash tool schema includes:
{
  "name": "shell",
  "type": "string",
  "description": "Shell to use: 'powershell' (default) or 'cmd'"
}

// WASM disabled tools
// SX_TOOL_BASH, SX_TOOL_BACKGROUNDBASH, SX_TOOL_READBGOUTPUT,
// SX_TOOL_LISTBGTASKS, SX_TOOL_KILLBGTASK, SX_TOOL_INVOKESKILL

Protocols

Contents

Overview

Transports

stdio

streamable-http

Message Types

Tool Registry

Tool Schemas

Server Implementations

scorpiox-mcp.c

scorpiox-mcp-httpclient.c

scorpiox-server.c

Platform Variants

Windows

WASM

Linux / macOS