AgentHQ

AgentHQ is a multi-tenant AI Agent Governance Platform that helps organizations safely operate, monitor, and govern AI agents through policies, approvals, audit trails, compliance reporting, incident management, and MCP integrations.

Organizations can create dedicated governance workspaces, invite users, assign roles, onboard MCP servers, and maintain visibility into AI agent activity across their environment.

Live Demo

Frontend: https://agenthq-seven.vercel.app/

Backend API: https://agenthq.onrender.com/docs

Current Version

AgentHQ v0.8.0

Project Status

AgentHQ is a live, multi-tenant Enterprise AI Agent Governance Platform focused on:

• Organization Workspaces
• Membership-Based Access
• Tenant Isolation
• Agent Governance
• Policy Enforcement
• Approval Workflows
• Execution Tracking
• Incident Management
• Audit Logging
• Compliance Reporting
• MCP Server Registration
• MCP Tool Discovery
• Authentication & RBAC
• Security Event Trails
• Centralized Abuse Protection
• Real MCP Tool Discovery
• Policy Simulation & Impact Analysis
• MCP Gateway Policy Enforcement
• Dual-Protocol REST and MCP Gateway
• AI Risk Register
• Compliance Controls and Evaluation
• Executive AI Risk Reporting

The Problem

Organizations are rapidly deploying AI agents across operations, customer service, knowledge management, and business workflows.

As the number of agents grows, organizations need answers to critical governance questions:

• Which agents exist?
• What tools can they access?
• Which actions require approval?
• Which executions were blocked?
• What incidents occurred?
• How do we audit agent activity?
• How do we generate compliance reports?

The Solution

AgentHQ provides:

• Agent Registry
• Agent Tools Registry
• Policy Rules
• Policy Decision Engine
• Approval Workflows
• Execution Tracking
• Incident Management
• Audit Logging
• Compliance Reporting
• Dashboard Analytics

AgentHQ v0.5.0

AgentHQ v0.5.0 adds real MCP protocol tool discovery while preserving the deterministic mock adapter for demos and tests.

• Connect to MCP servers over Streamable HTTP or SSE.
• Initialize an MCP client session and discover tools through tools/list.
• Select mock or real discovery with MCP_DISCOVERY_MODE.
• Configure bounded connection and request timeouts per MCP server.
• Reference bearer tokens or API keys through MCP_AUTH_* environment variables.
• Disable HTTP redirects and preserve existing linked agents, tools, and successful sync timestamps when discovery fails.
• Keep sync failures sanitized and auditable.

Real discovery imports tool definitions only. Governed tool calls are handled separately by the v0.6.0 MCP Gateway.

AgentHQ v0.5.1

AgentHQ v0.5.1 adds Tool Schema Governance for discovered MCP tools.

• Persist MCP input and output schemas with hashes, versions, and change timestamps.
• Detect discovered, removed, schema-changed, and description-changed tools during sync.
• Preserve manually assigned risk levels and permissions.
• Review discovered tools and audit risk or permission changes.
• Calculate governance status from human review and applicable policy coverage.
• View organization-scoped tool governance metrics, policy coverage, and formatted schemas.

Tool Schema Governance remains read-only; governed tool calls are handled separately by the v0.6.0 MCP Gateway.

AgentHQ v0.5.2

AgentHQ v0.5.2 adds proactive Governance Alerts and Monitoring.

• Generate organization-scoped alerts for new, removed, and changed MCP tools.
• Surface unreviewed, ungoverned, high-risk, and policy-coverage gaps.
• Prevent duplicate active alerts while preserving alert history.
• Acknowledge, resolve, and reopen alerts with audited lifecycle transitions.
• Calculate a governance health score from tool posture and unresolved alerts.
• Monitor recent alerts and governance gaps from the dashboard and Alert Center.

Notifications, email delivery, MCP tool execution, and tool calls remain intentionally out of scope.

AgentHQ v0.5.3

AgentHQ v0.5.3 adds read-only Policy Simulation and Impact Analysis.

• Preview a proposed policy before creating, updating, or enabling it.
• Identify affected tools, agents, and MCP servers.
• Compare current and projected policy coverage.
• See tools becoming blocked, approval-required, or explicitly allowed.
• Detect overlapping policies and conflicting effects.
• Estimate governance gaps and alerts that a policy may resolve.
• Review policy coverage percentage from the dashboard.

Simulations are organization-scoped and do not persist policies, create alerts, or change execution behavior.

AgentHQ v0.6.0

AgentHQ v0.6.0 introduces the MCP Gateway and turns governance policy decisions into an enforcement boundary for routed MCP tool calls.

• Issue hashed, revocable, server-scoped gateway tokens.
• List only enabled and reviewed or governed MCP tools.
• Evaluate policies before every gateway tool call.
• Block upstream calls when policy denies them.
• Require approved, organization-scoped approvals when policy requires approval.
• Forward allowed calls to real MCP servers through Streamable HTTP or SSE.
• Record execution status, latency, sanitized summaries, and gateway audit events.
• Prevent duplicate upstream calls with gateway-token, tool, and idempotency-key records.
• Rate limit gateway listing, calls, and credential management.

AgentHQ can enforce governance only for MCP traffic routed through the gateway. Production deployments requiring strict enforcement must prevent governed clients from reaching upstream MCP servers directly.

AgentHQ v0.7.0

AgentHQ v0.7.0 introduces a dual-protocol governed gateway for external AI agents.

• Issue agent-scoped credentials with explicit allowed MCP server sets.
• Connect MCP-compatible agents through a Streamable HTTP gateway.
• Connect custom agents through the REST gateway.
• Enforce the same policies, approvals, rate limits, execution tracking, and audit trail across both protocols.
• Deny disabled, archived, soft-deleted, cross-agent, and cross-organization access.
• Preserve REST idempotency and support MCP call idempotency metadata.

See GATEWAY_INTEGRATION.md for setup examples and the production direct-bypass safety model.

AgentHQ v0.8.0

AgentHQ v0.8.0 introduces the AI Risk & Compliance Center for enterprise governance visibility.

• Automatically maintain an organization-scoped AI Risk Register for discovered MCP tools.
• Evaluate five built-in, extensible compliance controls.
• Measure policy coverage, governance status, and compliance posture per tool.
• Calculate an explainable organization AI Risk Score and Compliance Score.
• Capture one lightweight daily risk snapshot when executive risk reporting is accessed.
• Surface compliance violations, critical coverage gaps, and critical unreviewed tools as governance alerts.
• Provide executive risk reporting, dashboard widgets, a Risk Register page, and an expanded Compliance Center.

Compliance evaluation is informational and does not change policy enforcement behavior.

AgentHQ v0.2.0

AgentHQ v0.2.0 introduces MCP Server Registration and Tool Discovery.

This allows AgentHQ to:

• Register MCP servers
• Track MCP server connection status
• Automatically create linked agents
• Discover tools from MCP servers
• Sync discovered tools into the Agent Tools Registry
• Preserve manually edited tool risk levels and permissions
• Prevent duplicate tools during repeated syncs
• Audit successful and failed MCP sync operations
• Show MCP server counts on the dashboard

See RELEASE_NOTES.md for the complete v0.2.0 release summary.

AgentHQ v0.3.0

Authentication & RBAC

Added:

• User management
• JWT authentication
• Login and registration
• Role-based access control

Roles:

• Admin
• Auditor
• Operator
• Agent Owner

Enterprise Access Control

Protected:

• Policy Rules
• MCP Servers
• Audit Logs
• Compliance Reports
• Executions
• Incidents
• Agent Management

Dashboard

Added:

• Total users
• Active users

AgentHQ v0.3.2

AgentHQ v0.3.2 focuses on reliability, performance, and production hardening.

Pagination

Added bounded pagination to:

• Agents
• Agent Tools
• MCP Servers
• Policy Rules
• Approvals
• Executions
• Incidents
• Audit Logs
• Users
• Compliance Incidents

Default:

• limit = 50
• max limit = 200

Database Performance

Added production indexes for:

• Audit Logs
• Executions
• Incidents
• Approvals
• Agent Tools
• Policy Rules
• MCP Servers

Query Optimization

Reduced query fan-out:

Dashboard Summary:

• 24 → 6 queries

Compliance Summary:

• 10 → 5 queries

Agent Compliance Report:

• 10 → 2 queries

Transaction Safety

Added service-owned atomic transactions for:

• Execution Creation
• Approval Decisions
• MCP Sync
• User Deactivation
• Policy Decision Evaluation

Critical governance actions now commit business mutations and audit logs atomically.

AgentHQ v0.4.0

AgentHQ v0.4.0 introduces multi-tenant organization foundations for independently governed enterprise workspaces.

Highlights:

• Organization workspaces and membership-based roles
• Organization bootstrap and administrator creation
• Organization invitations and invite acceptance
• Tenant-isolated governance resources
• Organization-aware dashboards, compliance reports, navigation, and onboarding
• Audit Logs frontend for organization admins and auditors

See RELEASE_NOTES.md for the complete v0.4.0 release summary.

AgentHQ v0.4.1

AgentHQ v0.4.1 focuses on security hardening for multi-tenant, production-facing deployments.

Highlights:

• Centralized organization authorization and tenant-isolation checks
• Membership-level administration and last-admin lockout prevention
• Append-only, organization-scoped audit logs and denied-access security events
• Recursive audit redaction and safe MCP error handling
• Production JWT, bootstrap, registration, and MCP URL safeguards
• Redis-backed production rate limiting with local in-memory fallback
• 429 Too Many Requests responses with Retry-After
• Rate-limit security audit events for protected operations

See SECURITY_AUDIT.md, AUTHORIZATION.md, AUDIT_LOGGING.md, and RATE_LIMITING.md for the security model and operational guidance.

Architecture Overview

Organization
|-- Memberships
|-- Agents
|-- MCP Servers
|-- Policy Rules
|-- Executions
|-- Incidents
|-- Audit Logs
`-- Compliance Reports

Organizations own governance resources, while memberships define each user's organization role. Tenant isolation prevents cross-organization access, audit logs provide governance visibility, policies govern execution behavior, and MCP integrations connect external agent ecosystems to the AgentHQ governance layer.

Architecture

AgentHQ uses a React frontend for the tenant-aware governance console, a FastAPI backend for API workflows, modular governance services for policy decisions and lifecycle rules, PostgreSQL persistence for organization-scoped operational records, and audit/compliance capabilities for reporting and review.

The architecture includes organization and membership context, tenant-isolation enforcement, JWT authentication, reusable RBAC enforcement, an MCP Server Registry, an MCP Discovery Layer that synchronizes discovered tools, and an MCP Gateway that enforces policies before forwarding approved tool calls upstream.

Core Capabilities

Multi-Tenant Organizations

• Organization workspaces
• Membership-based access
• Tenant isolation

Governance

• Policy Rules
• Policy Decision Engine
• Policy Simulation
• Policy Impact Analysis
• Approval Workflows
• Execution Tracking

Operations

• Incident Management
• Compliance Reporting
• Dashboard Monitoring

MCP Integration

• MCP Server Registration
• Tool Discovery
• Tool Governance
• MCP Gateway Policy Enforcement
• Real Governed Tool Calls
• Governance Alerts
• Governance Health Monitoring

Security & Reliability

• RBAC
• Audit Logging
• Atomic Transactions
• Failure Handling
• Pagination
• Performance Optimization
• Tenant Isolation
• Audit Redaction
• Security Event Trails
• Redis-Backed Rate Limiting

Tech Stack

Backend

• FastAPI
• PostgreSQL
• SQLAlchemy
• Alembic

Frontend

• React
• TypeScript
• Tailwind CSS
• TanStack Query

Infrastructure

• Docker Compose
• Supabase PostgreSQL
• Render
• Vercel
• Render Key Value / Redis

Quality

• 357 automated tests passing
• Ruff clean
• MyPy clean
• PostgreSQL migrations verified
• Dockerized deployment
• Render backend
• Vercel frontend
• Supabase PostgreSQL
• Query-count regression tests
• Atomic transaction safety
• Tenant isolation tests
• Append-only audit logging
• Centralized secret redaction
• Redis-backed production abuse protection

Organization Onboarding

Create Organization
        |
Create Organization Admin
        |
Invite Users
        |
Accept Invite
        |
Assign Roles
        |
Govern AI Agents

Each organization operates as an independently governed workspace. Membership roles control access, and tenant isolation ensures that users and governance resources remain separated across organizations.

Repository Structure

backend/
  app/
    api/
    core/
    db/
    models/
    repositories/
    schemas/
    services/
  alembic/
  tests/
  Dockerfile
  pyproject.toml

frontend/
  src/
    api/
    components/
    pages/
    routes/
    types/
  package.json

Docker Demo

Start PostgreSQL and the backend API:

docker compose up --build

The API container runs migrations before starting Uvicorn.

Open API docs:

http://localhost:8000/docs

Seed demo data manually:

docker compose exec api python -m app.seed

Stop the stack:

docker compose down

Reset local database data:

docker compose down -v

Production Deployment

AgentHQ is prepared for a Supabase PostgreSQL, Render backend, and Vercel frontend deployment.

Production configuration is environment-driven:

Backend:  DATABASE_URL, BACKEND_CORS_ORIGINS, JWT_SECRET_KEY, BOOTSTRAP_SECRET, REDIS_URL,
          ALLOW_PUBLIC_REGISTRATION, RATE_LIMITS_ENABLED, MCP_DISCOVERY_MODE
Frontend: VITE_API_BASE_URL

Use exact HTTPS origins in BACKEND_CORS_ORIGINS, keep backend credentials in secret storage, configure Render's internal Redis URL as REDIS_URL, apply migrations before serving a new version, and never seed production automatically. Protected operations fail closed when production rate limiting is unavailable. FastAPI interactive docs remain enabled for the current release and can be restricted at the edge when needed.

See DEPLOYMENT.md and RATE_LIMITING.md for the complete deployment and abuse-protection guidance.

Documentation

• Deployment Guide
• Demo Flow
• Release Notes
• Organization Authorization
• Audit Logging
• Rate Limiting
• Supabase RLS Audit
• Security Audit

Frontend

Install dependencies:

cd frontend
cp .env.example .env
npm install

Run the frontend:

cd frontend
npm run dev

Open:

http://localhost:5173

The Vite dev server proxies /api requests to http://localhost:8000 when VITE_API_BASE_URL is empty.

Build and lint:

cd frontend
npm run build
npm run lint

Backend Local Development

Install dependencies:

cd backend
cp .env.example .env
uv sync

Start PostgreSQL only:

cd ..
docker compose up -d postgres

Apply migrations:

cd backend
uv run alembic upgrade head

Seed demo data:

cd backend
uv run python -m app.seed

Run the API locally:

cd backend
uv run fastapi dev app/main.py

Test Real MCP Discovery Locally

Start a compliant MCP server with a Streamable HTTP or SSE endpoint, then configure the backend:

MCP_DISCOVERY_MODE=real
ALLOW_PRIVATE_MCP_URLS=true

For an authenticated server, store the credential in a backend-only environment variable:

MCP_AUTH_LOCAL_DEMO=replace-with-the-local-server-token

Register the server through the MCP Servers page or API:

{
  "name": "Local MCP Demo",
  "server_url": "http://127.0.0.1:9000/mcp",
  "transport_type": "streamable_http",
  "auth_type": "bearer",
  "auth_secret_ref": "MCP_AUTH_LOCAL_DEMO",
  "request_timeout_seconds": 30,
  "connect_timeout_seconds": 10
}

Run sync from AgentHQ. A successful sync creates or reuses the linked agent and imports discovered tool names and descriptions. Never place credentials in server_url.

Run backend checks:

cd backend
uv run pytest
uv run ruff check .
uv run mypy app tests

Create migrations:

cd backend
uv run alembic revision --autogenerate -m "describe change"

Demo Flow

1. Start Docker services.
2. Seed demo data.
3. Open the frontend at http://localhost:5173.
4. Review the Dashboard summary cards.
5. Open Agents and inspect tools for the Payment Operations Agent.
6. Use Policy Decision Tester with a high-risk action.
7. Create a simulated high-risk execution and observe policy enforcement.
8. Approve a pending approval.
9. Create or resolve an incident.
10. Review Compliance summary and incident report.

See DEMO.md for curl-based examples.

Screenshots

Screenshots can be added here once the visual demo flow stabilizes:

• Dashboard overview
• Agent detail and tools
• Policy decision tester
• Compliance summary

Roadmap

Completed

• Organizations
• Memberships
• Organization Bootstrap
• Organization Invitations
• Invite Acceptance
• Tenant Isolation
• Tenant-Aware UX
• Audit Logs UI
• MCP Server Registration
• MCP Tool Discovery
• Linked Agent Creation
• Tool Sync Auditing
• Authentication & RBAC
• JWT Authentication
• User Management
• Agent Ownership Enforcement
• Governance Workflows
• Compliance Reporting
• Performance Hardening
• Pagination
• Database Indexing
• Dashboard Optimization
• Compliance Optimization
• Atomic Transactions
• Rollback Testing
• Failure Handling
• Organization Authorization Hardening
• Security Event Trails
• Audit Redaction
• MCP URL and Error Hardening
• Centralized Rate Limiting
• Supabase RLS Lockdown
• Real MCP Protocol Integration

Upcoming

• Foundry Agent Registration
• Copilot Studio Agent Registration
• Cost Tracking
• Notifications
• Organization Switching
• SSO

Health Check

curl http://localhost:8000/health