MCP (Model Context Protocol)

MCP lets you connect ZeroSphere's agent to external servers that expose additional tools: database access, custom APIs, or project-specific scripts. Anything you can wrap in an MCP server becomes available to the agent.

How It Works

  1. Add servers to mcp.json
  2. ZeroSphere connects on startup (and reloads automatically when the file changes)
  3. The agent discovers available tools
  4. The agent uses them like built-in capabilities

Configuration

User-level (applies to all projects):

%USERPROFILE%\.zerosphere\mcp/mcp.json

Project-level (this project only, commit to share with your team):

your-project/mcp.json
your-project/.mcp.json
your-project/.zerosphere/mcp.json

Project-level config is checked first. All matching files are loaded.

Config Format

{
  "mcpServers": {
    "server-name": {
      "command": "uvx",
      "args": ["mcp-server-package"],
      "env": {
        "API_KEY": "your-key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

autoApprove lists tool names that run without prompting. Use only for read-only operations.

Installing uvx

Most MCP servers run via uvx. Install it once:

Installation (PowerShell):

winget install astral-sh.uv

uvx downloads and runs MCP server packages automatically. No separate server installation required.

Common Servers

Filesystem:

{
  "filesystem": {
    "command": "uvx",
    "args": ["mcp-server-filesystem", "/path/to/projects"],
    "autoApprove": ["read_file", "list_directory"]
  }
}

Git:

{
  "git": {
    "command": "uvx",
    "args": ["mcp-server-git"]
  }
}

SQLite:

{
  "sqlite": {
    "command": "uvx",
    "args": ["mcp-server-sqlite", "/path/to/db.sqlite"]
  }
}

Time:

{
  "time": {
    "command": "uvx",
    "args": ["mcp-server-time"]
  }
}

Auto-Approval

Safe to auto-approve (read-only):

  • read_file, list_directory, get_current_time

Never auto-approve (destructive):

  • write_file, delete_file, git_reset, database execute

Troubleshooting

Server not loading:

Test the server directly:

uvx mcp-server-time

Check the ZeroSphere output panel for connection errors.

Tool not found: Verify disabled is false. Ask the agent to list available MCP tools.

Permission denied: Approve when prompted, or add the tool to autoApprove if it is safe.