check_excessive_agency

Instructions

Implementation Reference

• server.py:455-567 (handler)

  The check_excessive_agency tool handler function. Registered with @mcp.tool() decorator, it assesses an AI agent for excessive permissions (OWASP A03). Takes parameters like agent_name, tools_available, tools_used_in_task, has_approval_gates, has_scope_limits, and dangerous capabilities (filesystem, network, code execution, data modification, communications). Returns JSON with risk level, issues, and recommendations for least privilege.

  @mcp.tool()
  def check_excessive_agency(
      agent_name: str,
      tools_available: int = 0,
      tools_used_in_task: int = 0,
      has_approval_gates: bool = False,
      has_scope_limits: bool = False,
      can_access_filesystem: bool = False,
      can_access_network: bool = False,
      can_execute_code: bool = False,
      can_modify_data: bool = False,
      can_send_communications: bool = False,
      caller: str = "",
      api_key: str = "",
  ) -> str:
      """Assess agent for excessive permissions (least privilege).
  
      Behavior:
          This tool is read-only and stateless — it produces analysis output
          without modifying any external systems, databases, or files.
          Safe to call repeatedly with identical inputs (idempotent).
          Free tier: 10/day rate limit. Pro tier: unlimited.
          No authentication required for basic usage.
  
      When to use:
          Use this tool when you need structured analysis or classification
          of inputs against established frameworks or standards.
  
      When NOT to use:
          Not suitable for real-time production decision-making without
          human review of results.
  
      Args:
          agent_name (str): The agent name to analyze or process.
          tools_available (int): The tools available to analyze or process.
          tools_used_in_task (int): The tools used in task to analyze or process.
          has_approval_gates (bool): The has approval gates to analyze or process.
          has_scope_limits (bool): The has scope limits to analyze or process.
          can_access_filesystem (bool): The can access filesystem to analyze or process.
          can_access_network (bool): The can access network to analyze or process.
          can_execute_code (bool): The can execute code to analyze or process.
          can_modify_data (bool): The can modify data to analyze or process.
          can_send_communications (bool): The can send communications to analyze or process.
          api_key (str): The api key to analyze or process.
  
      Behavioral Transparency:
          - Side Effects: This tool is read-only and produces no side effects. It does not modify
            any external state, databases, or files. All output is computed in-memory and returned
            directly to the caller.
          - Authentication: No authentication required for basic usage. Pro/Enterprise tiers
            require a valid MEOK API key passed via the MEOK_API_KEY environment variable.
          - Rate Limits: Free tier: 10 calls/day. Pro tier: unlimited. Rate limit headers are
            included in responses (X-RateLimit-Remaining, X-RateLimit-Reset).
          - Error Handling: Returns structured error objects with 'error' key on failure.
            Never raises unhandled exceptions. Invalid inputs return descriptive validation errors.
          - Idempotency: Fully idempotent — calling with the same inputs always produces the
            same output. Safe to retry on timeout or transient failure.
          - Data Privacy: No input data is stored, logged, or transmitted to external services.
            All processing happens locally within the MCP server process.
      """
      if err := _check_auth(api_key):
          return err
      if err := _rl(caller):
          return err
  
      issues = []
      dangerous_caps = {
          "filesystem_access": can_access_filesystem,
          "network_access": can_access_network,
          "code_execution": can_execute_code,
          "data_modification": can_modify_data,
          "send_communications": can_send_communications,
      }
  
      active_dangerous = {k: v for k, v in dangerous_caps.items() if v}
      if len(active_dangerous) >= 3:
          issues.append({"issue": f"Agent has {len(active_dangerous)} dangerous capabilities active",
                          "severity": "CRITICAL", "capabilities": list(active_dangerous.keys())})
  
      if can_execute_code and not has_approval_gates:
          issues.append({"issue": "Code execution without approval gates", "severity": "CRITICAL"})
      if can_send_communications and not has_approval_gates:
          issues.append({"issue": "Can send communications without approval", "severity": "HIGH"})
      if not has_scope_limits:
          issues.append({"issue": "No scope limitations defined", "severity": "HIGH"})
  
      if tools_available > 0 and tools_used_in_task > 0:
          utilization = tools_used_in_task / tools_available * 100
          if utilization < 20 and tools_available > 10:
              issues.append({"issue": f"Only {tools_used_in_task}/{tools_available} tools used ({utilization:.0f}%). Over-provisioned.",
                              "severity": "MEDIUM"})
  
      risk = "LOW"
      if any(i["severity"] == "CRITICAL" for i in issues):
          risk = "CRITICAL"
      elif any(i["severity"] == "HIGH" for i in issues):
          risk = "HIGH"
      elif issues:
          risk = "MEDIUM"
  
      return json.dumps({
          "agent": agent_name,
          "risk_level": risk,
          "tools_available": tools_available,
          "tools_used": tools_used_in_task,
          "dangerous_capabilities": active_dangerous,
          "has_approval_gates": has_approval_gates,
          "has_scope_limits": has_scope_limits,
          "issues": issues,
          "owasp_ref": "A03 - Excessive Agency",
          "recommendation": "Apply least privilege: remove unused tools, add approval gates for dangerous actions."
              if risk != "LOW" else "Agent follows least privilege principles.",
      }, indent=2)

• server.py:455-456 (registration)

  Tool registration via @mcp.tool() decorator on line 455. The FastMCP instance 'mcp' is created at line 127 in server.py.

  @mcp.tool()
  def check_excessive_agency(