MCP tools

simse extends with tools through MCP (Model Context Protocol). MCP defines how tools are discovered, described, and invoked over stdio or HTTP transports.

simse implements both sides of MCP:

• As a client, simse connects to external MCP servers and consumes the tools they expose. Connect a filesystem server, a database query tool, an API client, or any MCP-compatible tool.
• As a server, simse exposes its own capabilities -- the adaptive store, sandbox, and session management -- as MCP tools that other agents and systems can call.

What you can do with MCP tools

• Read and write files in your project
• Query databases and APIs
• Run shell commands in the sandbox
• Search the adaptive store from external agents
• Build custom tools that plug into your specific workflow

How MCP works

The MCP protocol defines a standard handshake for tool discovery. When simse connects to an MCP server, it:

1. Establishes a connection over the configured transport (stdio or HTTP)
2. Requests the server's tool list -- each tool has a name, description, and input schema
3. Registers the tools and makes them available in your sessions
4. Invokes tools on demand as the model requests them

Tool output is returned to the model, which uses it to continue the response. simse enforces output size limits (50,000 characters by default) and truncates longer outputs.

Transports

stdio transport

The MCP server runs as a child process. simse communicates with it over standard input and output. This is the most common transport for local tools:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  ]
}

The command field is a single executable; pass everything else as separate entries in args. simse manages the process lifecycle -- starting it on connection, restarting it on failure.

The MCP protocol itself also defines an HTTP transport for servers that run as standalone network services. Server entries in mcp.json configure stdio subprocesses; the command + args form shown above is the configuration simse uses.

simse as an MCP server

simse also exposes its capabilities as an MCP server. Other agents and systems can connect to simse and use:

• Adaptive store search -- Query the local knowledge store
• Library operations -- Import, search, and retrieve library entries
• Sandbox tools -- Run commands, read and write files
• Session management -- Create and interact with simse sessions

This makes simse composable with other agent systems and automation pipelines.

Tool permissions

Every tool invocation goes through permission checking. The configured permission mode determines what happens:

Mode	Behavior
"default"	Ask the user before each tool action
"acceptEdits"	Auto-approve file edits, ask for other actions
"plan"	Plan only -- list what tools would do, but do not execute
"dontAsk"	Auto-approve all tool actions

Permissions can also be granted per-action during a session with allow once or allow always.