Model Context Protocol (MCP)

Local tools use their direct canonical name (for example, read_file or execute_command) and external tools use mcp_<service>_<tool>, for example mcp_browser_service_browser_navigate. Permissions are stored under this full name: authorizing a tool does not authorize its namesake in another service. Legacy aliases are not supported. Special characters are encoded to prevent collisions.

1. What is MCP?

The Model Context Protocol (MCP) is an open protocol championed by Anthropic to bridge AI models with external tools and databases through a standardized interface.

In ZeroChat, the local server starts on 127.0.0.1 and opens GitHub Pages with a session token. You can install it from PyPI or run zerochat.py directly: both methods use the same web origin and do not require configuring a remote MCP URL.

2. Connection & UI Indicators

Open Settings → MCP to check the local-server status and discovered tools:

• Disconnected: The local server is not available. Keep zerochat or zerochat.py running and reload the page if it was restarted.
• Connected: ZeroChat has discovered the local tools and can list available external MCP services.

There is no manual connection form or button. Run the command below and open the app from the link started by the script. The session token protects requests to the local server; do not share that URL or token.

3. Local Server: PyPI or zerochat.py

The recommended option is to install the official executable from PyPI. It does not include a copy of the interface: it opens the same GitHub Pages app as the downloaded script.

Alternatively, download zerochat.py and run it with Python. Both options start the SSE server, open GitHub Pages, and retain the session token on the same web origin. They also create ~/zerochat/: it stores configuration, token, and services; Python MCPs use only ~/zerochat/.venv/, without installing packages into your global Python.

Core Local Tools:

• execute_command: Unified shell terminal for Git, CLI, test execution, and compilation, with automatic OS and environment diagnosis.
• read_file: Safe file reading with line range slicing and context token limits.
• edit_file: Atomic file writing and editing (overwrite, append, or chunk replacement).
• list_directory: Structured single-level folder listing and file metadata; it does not traverse subdirectories.

Session Token Security: All requests from GitHub Pages require the ephemeral token generated at startup. Without this valid token, the local server rejects any incoming connection.

# Recommended: install from PyPI
pip install zerochat && zerochat

# Alternative: download and run the script directly
curl -sL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py && python3 zerochat.py

4. Tool Permissions & Authorization Policies

Because local tools can perform sensitive operations on your system (such as modifying files or running shell commands), ZeroChat provides granular security controls for each tool:

Open Settings → Permissions to choose the global policy, review remembered decisions, and clear them when needed. In the MCP panel you can also choose Ask, Allow, or Deny for each tool.

• On/Off Switches: Enable or disable each tool sent to the model without stopping the server.
• Authorization Policy:
  • Ask for authorization (recommended): ZeroChat pauses to ask for explicit approval.
  • Allow all: Any tool runs without confirmation. Use it only in a trusted environment.

The Allowed directories list centralizes access for local file tools. Add one rule per line with R: for reading, W: for modification, or RW: for both; for example, R:./project/** or W:./project/src/**. Use * for one segment and ** to include subdirectories. Paths that do not match a rule require authorization.

For execute_command, ZeroChat examines only simple commands and their explicit paths. A read path needs R: and a modifying path needs W:. Pipes, redirections, expansions, wildcards, and other ambiguous shell constructs always require one-time authorization.

5. External MCP Services & Individual Activation

The local server manages external MCP services in ~/zerochat/services/. You do not need to run a global external daemon: start and stop each service from ZeroChat. Deleting ~/zerochat/ removes local state and every installed MCP.

In Settings → MCP, "Available MCP Servers" lets you start or stop each service and configure its options. When starting one, ZeroChat installs dependencies when needed, discovers its tools, and adds them to the panel. Node.js-based services require Node.js 18 or later and npm.

The local server provides ready-to-use definitions in services/:

• dummy_mcp: Minimal test service in pure Python without external dependencies.
• playwright: Browser automation with the official Playwright MCP server; the Headless option controls whether a browser window is shown.
• memory: Knowledge graph and structured persistent memory.
• lsp: Language Server Protocol for code navigation and type inspection.

Web-interface patches such as 7.4.x arrive from GitHub Pages without updating the executable. Only a major.minor change, for example 7.4 to 7.5, requires updating zerochat.py or the PyPI package.