M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
C

CUGA Generalist Agent Harness

Community
Framework / SDK
A configurable generalist agent harness for the enterprise

This is a framework for building MCP servers or agents, not a server you connect a client to.

How to install ↓ Compare GitHub source repository ↗
Category
Other #158 of 230
Stars
★ 1.0k Very popular
Transport
stdio (local process) · SSE · Streamable HTTP
Runtime
Python 3.12+ · Node.js · Docker
Credentials
API key / credential required
License
Apache-2.0
Last commit
Tools
2
49FMRS · D

CUGA is an open-source generalist agent harness focused on enterprise governance: policy system, sandboxed execution, multi-agent supervision, and a knowledge engine. It can act as an MCP client and be exposed to other agents as MCP, making it suited to teams that want to plug domain tools and policies into a generalist agent. Budget for your own LLM credentials and define sandbox and policy boundaries before use, since default local execution offers weaker isolation.

Strongest · Documentation 13/20 Weakest · Security and permissions 7/20

Reliability
8/20
Security and permissions
7/20
Maintenance
12/20
Documentation
13/20
Setup experience
9/20
Why each score
Reliability 8/20
Static, source-only review; nothing was executed. The README claims #1 positions on AppWorld and WebArena, but those are external leaderboard badges that cannot be verified from the supplied material and are not scored. The project is a large enterprise agent harness (demos, supervisor, knowledge, a separate events service, Helm deployment), so the MCP init and tool-list handshake path is not concretely demonstrated. The README enumerates a test matrix (unit, policy integration, SDK, stability with an 87% gate), but no CI workflow contents or committed test coverage for the server's key paths are shown, so this cannot be credited under the static calibration. The cap of 12 applies; deductions for unverifiable key paths, unconfirmed tool-behavior match, and a broad dependency surface (Python 3.12, uv, optional extras, browser extension, container/E2B sandboxes).
Security and permissions 7/20
Positive signals exist: a policy framework (Intent Guard, Tool Approval with human-in-the-loop confirmation, Tool Guide, Output Formatter), HITL gates, code sandboxes (local / Docker-Podman / E2B isolation), and tool-call budgets, which support least-privilege and confirmation goals. However, several items widen the boundary: README examples contain credential-shaped assignments (OPENAI_API_KEY=... in .env, though placeholders), E2B usage requires exposing the local registry/service publicly via ngrok, MCP servers are launched as stdio commands via uvx, and final_answer.function imports and calls a dotted-path function with no sandbox (README itself warns to point it only at trusted code). No malware, credential theft, covert exfiltration, or default irreversible delete/pay/deploy signals appear, so the 0-4 red-line band does not apply; the score is held below the midpoint because permission scoping, confirmation completeness, and external exposure are not end-to-end verifiable here.
Maintenance 12/20
Evidence is limited. The description shows 876 stars, 177 open issues, and an unarchived repository, and the README shows a live feature matrix and roadmap, indicating activity. But the license field is NOASSERTION, meaning the license is not identified in the supplied material, which is a real governance gap. No release history, commit cadence, dependency-update policy, or security-response channel is verifiable, and the issue count is high with no response-time evidence. Scored at the 'active but governance/versioning gaps' anchor without inflation.
Documentation 13/20
The documentation is layered: quick start, multi-provider LLM configuration (OpenAI/WatsonX/Azure/Groq/RITS/OpenRouter/wxO), mode and settings tables, sandbox and knowledge-base sections, supervisor, shortlister, and tool-integration examples, with many pointers to docs.cuga.dev and in-repo paths. Some limitations are disclosed explicitly (run receipts measure tokens not cost; final_answer instructions are ignored in default Lite mode; supervisor-synthesized answers are not shaped). Gaps remain: license is undeclared, the server manifest is not cached, cost/quota and troubleshooting coverage is uneven, and much detail lives on external sites that cannot be reviewed here, so it falls short of the top band.
Setup experience 9/20
Clear entry steps are given: git clone, uv venv --python=3.12, uv sync, write .env, then `cuga start demo_crm --read-only`, plus multiple optional paths (sandbox, E2B, supervisor, knowledge, skills, Helm). Complexity is introduced by platform prerequisites and container runtimes (Rancher Desktop/Docker, E2B CLI, ngrok) and by hybrid/browser modes needing Chromium plus a browser extension. No verifiable install output or CI config body is present in the static evidence, so the calibration cap of 15 applies; points are deducted for the multi-branch, multi-dependency, non-single-command fragility.

Static review · not runListed 2026-09-10

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesRuns commands or codeUses the networkControls a browserConnects to a database

Best for

  • Enterprise agent teams that need governable, auditable policies
  • Developers who want a generalist agent they only configure with domain tools and policies
  • Hybrid workflows that must combine browser interaction with API calls
  • Teams using the Python SDK or self-hosting on Kubernetes

Not for

  • Lightweight scenarios that only need a single simple tool call
  • Offline users who cannot supply any LLM API key or self-hosted model
  • End users expecting zero-configuration out-of-the-box use

Required permissions

  • Reading the repository and local workspace files (e.g. files under cuga_workspace)
  • Network access to LLM providers, OpenAPI services, and MCP servers
  • In hybrid/web mode, controlling browser pages through the browser extension and Playwright
  • Accessing Docker/Podman or E2B cloud execution environments when sandboxing is enabled
  • In manage mode, drafting and publishing agent configuration (tools, MCP, LLM, policies)

Risks and side effects

  • The agent can call real APIs and act on web pages on the user's behalf, so mistakes can have real business impact
  • Misconfigured policies or sandboxes weaken isolation; local Python execution is the default and is less isolated
  • Exposing the local registry to E2B via tunnels such as ngrok increases the attack surface
  • The knowledge base and saved trajectories may contain sensitive enterprise data that you must store and access-control yourself
  • Runs against self-hosted or internal models, so token and cost accounting must be converted with your own rates

Setup

Before you start

Runtime：Python 3.12+ · Node.js · Docker

OPENAI_API_KEY requiredsecret OpenAI API key, created on the API keys page at platform.openai.com.
WATSONX_API_KEY optionalsecret IBM WatsonX API key from your WatsonX project or space.
AZURE_OPENAI_API_KEY optionalsecret Azure OpenAI service API key from the Azure portal.
GROQ_API_KEY optionalsecret Groq platform key, generated at console.groq.com/keys.
OPENROUTER_API_KEY optionalsecret OpenRouter gateway key from your account settings at openrouter.ai.
RITS_API_KEY optionalsecret IBM internal RITS inference platform key, obtained from the RITS platform admin.
WXO_API_KEY optionalsecret watsonx Orchestrate tenant API key, generated under Settings -> API details.
E2B_API_KEY optionalsecret E2B cloud sandbox key created at e2b.dev/dashboard (only needed for E2B sandbox mode).
Other optional settings (1)
AGENT_SETTING_CONFIG optional Selects the LLM settings file (e.g. settings.openai.toml, settings.watsonx.toml); not a credential.
  1. Ensure Python 3.12+ and the uv package manager are installed.
  2. Clone and enter the repository: git clone https://github.com/cuga-project/cuga-agent.git && cd cuga-agent
  3. Create and activate a virtual environment: uv venv --python=3.12 && source .venv/bin/activate
  4. Install dependencies: uv sync
  5. Configure model credentials, e.g. write OPENAI_API_KEY=your-key to .env and point AGENT_SETTING_CONFIG at the matching settings.*.toml.
  6. Start a demo: cuga start demo_crm --read-only; Chrome opens at https://localhost:7860.
  7. Optional: run cuga viz to inspect agent trajectories; configure custom tools and MCP servers in src/cuga/backend/tools_env/registry/config/mcp_servers.yaml.

Check that it works

Run `cuga start demo_crm --read-only`, open https://localhost:7860, and send 'from contacts.txt show me which users belong to the crm system'; if find_tools and load_skill appear in the tool list and return tool/skill content, the setup works.

Troubleshooting

  1. If startup fails, confirm Python 3.12+ and that uv sync completed
  2. If model calls fail, check the API keys in .env and that AGENT_SETTING_CONFIG points at a matching TOML file
  3. If E2B reports 'function_call_host not configured', set a public ngrok URL under server_ports in settings.toml
  4. If sandboxing is unavailable, run cuga test-sandbox or cuga test-sandbox --remote to verify the environment
  5. If skills are not discovered, check the [skills] root setting, confirm SKILL.md has name and description frontmatter, and restart the service to rescan
  6. If a large tool catalogue makes prompts too long, adjust [shortlister] strategy and threshold settings

Things to try

Once connected, you can ask your AI assistant things like:

  • Find me a tool that can send email
  • List your available skills and load the one relevant to this task
  • From contacts.txt show me which users belong to the crm system
  • Get top account by revenue from digital sales then add it to current page

Tools 2

load_skill read-only
Loads the full instruction body of a matching SKILL.md on demand when a task matches that skill.
find_tools read-only
Searches a large tool catalogue and lists the tools relevant to the current task.

Use cases

Orchestrating complex tasks that span web pages and REST APIs in an enterprise setting
Connecting self-hosted MCP servers and OpenAPI services via mcp_servers.yaml
Constraining agent behaviour with policies and human-in-the-loop approvals
Building multi-agent supervision and delegating to remote A2A agents
Running RAG question answering over internal documents
Packaging domain workflows as SKILL.md skills loaded on demand

Supported clients

CUGA SDK
MCPPartial support

Listed from the project's documentation, not tested by this site.

Overview

CUGA (Configurable Generalist Agent) is an open-source generalist agent harness for the enterprise, supporting complex task execution on the web and over APIs. It integrates tools through OpenAPI specs, MCP servers, and LangChain, and ships with a composable architecture, selectable reasoning and code-generation modes (fast / balanced / accurate), API/web/hybrid task modes, multi-agent supervision via CugaSupervisor (including remote A2A agents), a five-type policy system (Intent Guard, Playbook, Tool Approval, Tool Guide, Output Formatter) with human-in-the-loop approvals, a built-in Docling-based RAG knowledge engine with agent- and session-level scopes, agent skills loaded on demand from SKILL.md files, tool-call budgets, reflection, and sandboxed code execution via Docker/Podman or E2B. It offers a Python SDK, a web manage-and-publish UI for versioned configuration, and a Helm chart for self-hosting on Kubernetes.

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 659 · Tools 11 Compare with this →
Compare with other MCP servers

Source revision 93a630a68d93 Data synced 2026-10-19 Read the FMRS scoring method