STDIO Transport

The STDIO transport runs a local MCP server as a child process. ChatShell starts the process, communicates with it over stdin/stdout, and automatically discovers the tools it provides.

Configuration

1. Go to Settings → MCP Servers
2. Click Add Server
3. Select STDIO as the transport type
4. Fill in the configuration fields
5. Click Test Connection to verify
6. Click Save

Tip: Already have a claude_desktop_config.json or similar config file? Click Paste JSON config to import the server definition directly — no manual field entry needed. See JSON Config Import for supported formats.

Configuration Options

Field	Required	Description
Command	Yes	The executable to run (e.g., npx, node, python)
Args	No	Command-line arguments as a list
Env	No	Environment variables to set for the process
Working Directory	No	Working directory for the process (defaults to home directory)

Example: npx-based Server

Many MCP servers are distributed as npm packages and can be run directly with npx:

Command: npx
Args: -y @modelcontextprotocol/server-filesystem /Users/you/projects

This runs the Filesystem MCP server, giving the AI enhanced filesystem access to the specified directory.

Example: Python Server

Command: python
Args: -m my_mcp_server
Working Directory: /Users/you/my-mcp-project

Environment Variables

Use the Env field to pass configuration to the MCP server:

{
  "API_KEY": "your-api-key",
  "BASE_URL": "https://api.example.com"
}

Security note: ChatShell sanitizes the environment passed to STDIO processes. Only essential system variables (PATH, HOME, USER, SHELL, etc.) are inherited automatically. All other variables must be explicitly configured in the Env field.

Common STDIO MCP Servers

Server	Command	Description
Everything	npx -y @modelcontextprotocol/server-everything	Sample server for testing
Filesystem	npx -y @modelcontextprotocol/server-filesystem /path	Enhanced file access
GitHub	npx -y @modelcontextprotocol/server-github	GitHub API tools
Brave Search	npx -y @modelcontextprotocol/server-brave-search	Brave Search API

Troubleshooting

Process fails to start Check that the command is installed and in your PATH. For npx, ensure Node.js is installed.

No tools discovered The process may have crashed on startup. Check the logs in ChatShell’s developer console.

Environment variable not found Remember that environment variables are not automatically inherited. Add them explicitly in the Env field.