Global and Project level MCP Server + ability to toggle individual MCP tools

[TerminallyLazy]

Summary

• Implements true project-level MCP server isolation as designed in the UI
• Fixes bug where global MCP servers would "spill over" into projects even when disabled at the project level
• Ensures project-specific MCP servers are properly shown to the agent when a project is active
• Adds UI components for managing project-specific MCP server configurations

Problem

When working within a project context, Agent Zero was incorrectly reporting global MCP tools (even when toggled OFF at the project level) instead of the project-specific MCP tools that were actually configured and enabled.
The UI clearly states: "Configure MCP servers for this project. These are separate from global MCP servers." However, the backend was not honoring this separation.

Root Cause

The MCPConfig class in mcp_handler.py was designed to merge global and project servers rather than treat them as separate:

OLD (broken) behavior

all_servers = list(self.servers)  # Always include ALL global servers
if project_name and project_name in self.project_servers:
    all_servers = all_servers + list(self.project_servers[project_name])  # Add project on top

This affected four critical methods:

• get_tools_prompt() - Builds the MCP tools section for agent prompts
• get_server_detail() - Returns server information
• has_tool() - Checks tool availability
• call_tool() - Executes MCP tools

Solution

Changed the logic to use exclusive project servers when a project context is active:

NEW (fixed) behavior

if project_name and project_name in self.project_servers:
    all_servers = list(self.project_servers[project_name])  # ONLY project servers
else:
    all_servers = list(self.servers)  # Fall back to global only when no project

Behavior After Fix

Scenario	Old Behavior	New Behavior
Project with imported servers	Shows global + project (duplicates, wrong tools)	Shows ONLY project servers
Project with empty MCP config {}	Falls back to global servers	Shows NO servers (intentional)
Project without any MCP config	Uses global servers	Uses global servers (fallback)
No project active	Uses global servers	Uses global servers

Commits

Commit 1: 06e4c09 - Refactor MCP tool management and enhance project integration

• Added project_name parameter to get_tools_prompt() for project-aware prompt generation
• Added disabled_tools field to MCPServerRemote and MCPServerLocal models
• Added project-level tool filtering via load_project_mcp_tools()
• Created python/api/project_mcp_tools.py for API endpoint handling
• Added new UI component project-edit-mcp-tools.html for project MCP configuration
• Enhanced mcp-servers-store.js with tool toggling and state management

Commit 2: caaaf39 - Enhance MCP server management and project integration

• Added project_servers dict to MCPConfig for storing project-specific server instances
• Implemented load_project_servers() and unload_project_servers() methods
• Fixed get_server_detail() to respect project isolation
• Fixed get_tools_prompt() to use ONLY project servers when project is active
• Fixed has_tool() to check ONLY project servers when project is active
• Fixed call_tool() to execute ONLY project server tools when project is active
• Updated MCPTool.execute() to pass project context
• Updated get_tool() to pass project context to has_tool()
• Fixed has_servers check in get_mcp_tools_prompt() to properly detect project vs global availability
• Removed ProjectMcpTools API (functionality integrated into new system)
• Enhanced projects-store.js for better MCP server state management

Files Changed

Backend

File	Changes
python/helpers/mcp_handler.py	Core fix: project server isolation in all server access methods
python/extensions/system_prompt/_10_system_prompt.py	Updated has_servers check for project-aware detection
python/helpers/projects.py	Added MCP server management functions, import_global_mcp_server_to_project()
python/api/project_mcp_servers.py	New API for project MCP server management
python/api/mcp_server_get_detail.py	Added project_name parameter support
python/helpers/mcp_server.py	Minor integration updates

Frontend

File	Changes
webui/components/projects/project-edit-mcp-tools.html	New/refactored UI for project MCP configuration
webui/components/projects/projects-store.js	Enhanced MCP server state management
webui/components/settings/mcp/client/mcp-server-tools.html	Improved tool toggle UI
webui/components/settings/mcp/client/mcp-servers-store.js	Enhanced tool toggling and state management

Testing

To verify the fix:

1. Create a new project
2. Go to project settings → MCP Tools tab
3. Do NOT import any global servers (leave all toggles off)
4. Save and activate the project
5. Ask Agent Zero: "What MCP tools do you have?"
6. Expected: Agent reports no MCP tools (or only project-specific ones if configured)
7. Previously broken: Agent would report global MCP tools despite being disabled

Additional Test Cases

• Import a global server to a project → verify only that server's tools are available
• Disable specific tools within an imported server → verify those tools are hidden
• Switch between projects → verify each project shows only its configured servers
• Deactivate project → verify global servers become available again

Breaking Changes

None. This is a bugfix that aligns backend behavior with the documented UI design. Projects that were relying on the (incorrect) merge behavior will now see only their explicitly configured servers.

Related Issues

Fixes the issue where global MCP servers configured at the system level were incorrectly appearing in project contexts where they had been explicitly disabled or not imported.