simse implements the Model Context Protocol (MCP) for tool discovery, description, and invocation. simse supports both sides of MCP: as a client that consumes tools from external servers, and as a server that exposes its own capabilities to other agents.
simse participates in MCP in two roles simultaneously:
| Role | Description |
|---|---|
| Client | Connects to external MCP servers and uses the tools they expose |
| Server | Exposes simse capabilities as MCP tools that other agents can call |
MCP defines two transport mechanisms. simse supports both.
The MCP server runs as a subprocess. simse spawns the process and communicates over its standard input and output streams. This is the transport used for MCP servers configured in mcp.json.
Server entries in mcp.json configure stdio subprocesses. The command field is a single executable; all arguments go in args:
{
"servers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/path/to/project"]
}
]
}The subprocess is started on demand and kept alive for the session duration. If the subprocess exits unexpectedly, simse removes the tool and optionally attempts to restart it.
The MCP protocol also defines an HTTP transport, in which the server runs as a standalone network service and the client communicates with it over HTTP via JSON-RPC. This is a protocol-level transport; mcp.json server entries configure stdio subprocesses (the command + args form shown above) rather than HTTP endpoints.
When simse connects to an MCP server, it calls tools/list to discover available tools. The server returns an array of tool definitions.
| Field | Type | Description |
|---|---|---|
name | string | Unique tool identifier within the server |
description | string | Human-readable description of what the tool does |
inputSchema | object | JSON Schema describing the tool's input parameters |
Discovered tools are registered under a namespaced name: {server-name}/{tool-name}. This prevents collisions when multiple MCP servers expose tools with the same name.
If the server supports it, simse subscribes to tools/list_changed notifications. When the server sends this notification, simse re-fetches the tool list and updates its registry. This allows tools to be added or removed from a running server without restarting simse.
To call an MCP tool, simse sends a tools/call request to the server:
{
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {
"path": "/path/to/file"
}
}
}The server responds with the tool result:
{
"content": [
{
"type": "text",
"text": "file contents here..."
}
],
"isError": false
}Results with isError: true are treated as tool failures. The error message is reported to the backend and logged.
When acting as an MCP server, simse exposes the following features to connecting clients:
Clients can send log messages to simse via the logging/setLevel and logging/message methods.
simse supports the completion/complete method, allowing clients to request autocomplete suggestions for tool arguments. This is useful for IDE integrations and other interactive clients.
simse exposes filesystem roots via the roots/list method. Clients use roots to understand which directories are accessible.
simse supports resource templates that allow clients to request resources with parameterized URIs. Templates resolve to session data or library entries.
Clients can list available resources with resources/list and fetch individual resources with resources/read. Resources include session summaries and library content.
client → initialize → simse MCP server
client ← initialize (resp) ← simse MCP server (server info, capabilities)
client → initialized → simse MCP server
client → tools/list → simse MCP server
client ← tools/list (resp) ← simse MCP server (tool definitions)
...tool calls...
The initialize exchange negotiates the protocol version and declares capabilities. simse declares support for: tools, logging, completions, roots, resources, resourceTemplates, and listChanged.
simse maintains a connection to each configured MCP server. If a server becomes unreachable, the associated tools are marked unavailable. simse does not fail the session — unavailable tools are simply not offered to the backend until the server reconnects.