BIGHUB

@bighub/bighub-mcp

BIGHUB's Better Decision layer as an MCP server. Turn proposed IT agent actions into better decisions before they run from any MCP-compatible client.

MCP server for better decisions on IT agent actions.

MCP client
   ↓
@bighub/bighub-mcp
   ↓
BIGHUB API
   ↓
proposed action → Decision Packet → DecisionBrain → decision signals → run / review / context / block

---

Table of contents

Start here

• Install
• Quickstart
• When to use bighub-mcp
• Typical MCP Loop
• Better Decision primitives
• Trajectory-aware evaluation

Tool reference

• Better Decision primitives · Core loop · Actions · Outcomes · Decision cases · Precedents · Calibration · Multi-signal retrieval · Insights · Simulations · Learning · Features · Runtime ingestion · System integrations · Operating constraints · Approvals & kill switch · Events · Webhooks · API keys · Auth · Utility

Reference

• Environment Variables · Local Development · Links

---

Install

npm install @bighub/bighub-mcp

Requires Node.js 18+.

---

Quickstart

Set your API key:

export BIGHUB_API_KEY=your_api_key

Run the server in stdio mode:

npx @bighub/bighub-mcp

Add it to your MCP client configuration:

{
  "mcpServers": {
    "bighub": {
      "command": "npx",
      "args": ["@bighub/bighub-mcp"],
      "env": {
        "BIGHUB_API_KEY": "your_api_key"
      }
    }
  }
}

Works with MCP-compatible clients such as Claude Desktop and Cursor.

---

When to use bighub-mcp

Use this server when your MCP-connected agent proposes IT actions such as:

• granting Okta access
• rotating credentials
• deploying or rolling back services
• changing CI/CD, cloud, or IAM settings
• exporting sensitive data
• posting incident or support updates
• resolving actions that need human review

If your agent only answers questions or performs read-only lookups, you don't need this. It's designed for agents that make decisions with real-world consequences.

---

Typical MCP Loop

1. Send the proposed IT action to bighub_decide
2. Let BIGHUB build or use a Decision Packet
3. Run DecisionBrain and return execution mode, review/context flags, and a decision path when available
4. Execute only when can_run is true and no blocking flags are set
5. Route to review when BIGHUB asks for human approval or modification
6. Optionally report the outcome later

bighub_decide
→ bighub_build_packet / bighub_run_brain
→ bighub_resolve_review when needed
→ bighub_report_outcome later, optional

---

Better Decision primitives

The modern MCP surface is centered on the decision flow:

Field	Description
bighub_decide	Turn a proposed IT action into a better decision
bighub_build_packet	Build a Decision Packet from action and context
bighub_run_brain	Run DecisionBrain on a packet
bighub_list_reviews	List pending reviews
bighub_resolve_review	Approve, deny, or modify the reviewed action
bighub_get_system_context	Fetch context for Okta, Slack, or a configured integration provider
bighub_get_world_state	Read operational world state
bighub_report_outcome	Optionally report what happened later
bighub_http_request	Low-level fallback for endpoints not yet modeled

bighub_decide and bighub_run_brain return a normalized decision object first: recommended_action, mode, can_run, needs_review, needs_more_context, should_not_run, risk, confidence, expected_regret, reason, system, selected_model when available, decision_path when available, and counts for verification steps and obligations. The original backend payload is still available under raw for advanced callers. Legacy tools such as bighub_actions_evaluate remain available for compatibility.

bighub_build_packet uses the same canonical JSON SHA-256 hashing strategy as the Python SDK, so packet hashes match across SDK and MCP clients.

---

Trajectory-aware evaluation

BIGHUB evaluates actions not only in isolation, but also in the context of what happened before. As deployment, review, and outcome history accumulates, similar IT actions can receive better recommendations over time.

---

Complete Tool Reference

BIGHUB tools are organized by domain. The core loop tools are listed first.

---

Core loop

Tool	Description
bighub_decide	Modern Better Decision entry point
bighub_build_packet	Build a Decision Packet
bighub_run_brain	Run DecisionBrain
bighub_report_outcome	Optionally report what happened later
bighub_actions_evaluate	Legacy / low-level action evaluation

---

Actions

Tool	Description
bighub_actions_evaluate	Legacy / low-level action evaluation
bighub_actions_evaluate_payload	Evaluate with a free-form payload
bighub_actions_evaluate_batch	Evaluate multiple actions in one request
bighub_actions_dry_run	Non-persistent evaluation (preview)
bighub_actions_live_connect	Open a live connection slot
bighub_actions_live_heartbeat	Heartbeat a live connection
bighub_actions_live_disconnect	Close a live connection
bighub_actions_verify_validation	Verify a validation hash
bighub_actions_observer_stats	Observer statistics
bighub_actions_dashboard_summary	Dashboard summary metrics
bighub_actions_status	Service status
bighub_actions_memory_ingest	Ingest decision memory events
bighub_actions_memory_context	Retrieve memory context
bighub_actions_memory_refresh_aggregates	Refresh memory aggregates
bighub_actions_memory_recommendations	Pattern-based recommendations from memory

---

Outcomes

Tool	Description
bighub_outcomes_report	Report a real-world outcome
bighub_outcomes_report_batch	Batch report outcomes
bighub_outcomes_get	Get outcome by request_id
bighub_outcomes_get_by_validation	Get outcome by validation_id
bighub_outcomes_get_by_case	Get outcome by case_id
bighub_outcomes_timeline	Full outcome timeline
bighub_outcomes_pending	Decisions awaiting outcomes
bighub_outcomes_analytics	Outcome analytics summary
bighub_outcomes_taxonomy	Supported outcome statuses
bighub_outcomes_recommendation_quality	Follow rate, quadrants, trend, by domain/actor
bighub_outcomes_partner_view	Self-contained domain view with KPIs and examples

---

Decision cases

Tool	Description
bighub_cases_create	Create a decision case
bighub_cases_get	Get a case by ID
bighub_cases_list	List and filter cases
bighub_cases_report_outcome	Report outcome for a case
bighub_cases_precedents	Precedent intelligence for a proposed action
bighub_cases_calibration	Calibration metrics for cases

---

Precedents

Tool	Description
bighub_precedents_query	Query similar past cases
bighub_precedents_signals	Aggregated precedent signals
bighub_precedents_stats	Precedent index statistics

---

Calibration

Tool	Description
bighub_calibration_report	Calibration report
bighub_calibration_reliability	Reliability diagram data
bighub_calibration_drift	Calibration drift over time
bighub_calibration_breakdown	Breakdown by domain or tool
bighub_calibration_feedback	Calibration feedback signals
bighub_calibration_observe	Submit a calibration observation
bighub_calibration_quality_history	Daily quality score over time

---

Multi-signal retrieval

Tool	Description
bighub_retrieval_query	Multi-signal precedent retrieval
bighub_retrieval_query_explained	Retrieval with explanation trace
bighub_retrieval_strategies	List available strategies
bighub_retrieval_strategy	Get one strategy's details
bighub_retrieval_index_case	Manually index a case
bighub_retrieval_compare	Compare two strategies
bighub_retrieval_stats	Retrieval index statistics

---

Insights

Tool	Description
bighub_insights_advise	Learned advisories for an action
bighub_insights_patterns	Discovered risk patterns
bighub_insights_learn	Learning refresh
bighub_insights_profile	Action/tool profile

---

Simulations

Tool	Description
bighub_simulations_list	List simulation snapshots
bighub_simulations_get	Get a snapshot
bighub_simulations_by_request	Get snapshot by request
bighub_simulations_compare	Compare predicted vs actual
bighub_simulations_accuracy	Domain-level accuracy
bighub_simulations_stats	Simulation statistics

---

Learning

Tool	Description
bighub_learning_strategy	Current learning strategy
bighub_learning_runs	Recent learning runs
bighub_learning_recompute	Trigger learning recomputation
bighub_learning_backfill	Backfill learning artifacts

---

Features

Tool	Description
bighub_features_compute	Compute features for an action
bighub_features_compute_batch	Batch feature computation
bighub_features_snapshot	Create a feature snapshot
bighub_features_get_snapshot	Get a snapshot
bighub_features_list_snapshots	List snapshots
bighub_features_explain	Explain features for a case
bighub_features_export	Export features for a case
bighub_features_export_batch	Batch export
bighub_features_compare	Compare feature sets
bighub_features_schema	Feature schema
bighub_features_stats	Feature statistics

---

Runtime ingestion

Tool	Description
bighub_ingest_event	Ingest a single event
bighub_ingest_batch	Ingest events in batch
bighub_ingest_reconcile	Reconcile outcome with event
bighub_ingest_lifecycles	List event lifecycles
bighub_ingest_lifecycle	Get lifecycle for one event
bighub_ingest_pending	Events pending reconciliation
bighub_ingest_stale	Stale unreconciled events
bighub_ingest_stats	Ingestion statistics
bighub_ingest_adapters	List available adapters

---

System integrations

Tool	Description
bighub_systems_list_connections	List configured system integrations
bighub_systems_get_connection	Get one provider connection summary
bighub_systems_test_connection	Test unsaved provider config
bighub_systems_save_connection	Save provider config with optional display_name
bighub_systems_delete_connection	Delete provider connection
bighub_systems_poll_now	Trigger one provider poll now
bighub_systems_get_poll_schedule	Get provider poll schedule
bighub_systems_update_poll_schedule	Configure provider polling
bighub_systems_poll_history	Read redacted provider poll history
bighub_systems_poll_status	Scheduler status and due counts
bighub_systems_poll_metrics	Provider success/failure, latency, stale schedule and verifier metrics
bighub_systems_run_due_polls	Run due polls for the current organization

Supported system providers include okta, slack, github, sentry, datadog, aws_cloudtrail, terraform, kubernetes, argocd, gitlab, jenkins, azure, prometheus, grafana, and openshift. Common aliases such as github-ci, cloudtrail, terraform-cloud, k8s, argo-cd, gitlab-ci, and ocp are normalized to backend provider IDs.

Poll snapshots and histories are redacted before persistence and exposure. They provide best-effort operational context; they are not a replacement for production monitoring.

---

Operating constraints

Tool	Description
bighub_constraints_create	Create a constraint
bighub_constraints_list	List constraints
bighub_constraints_get	Get a constraint
bighub_constraints_update	Update a constraint
bighub_constraints_delete	Delete a constraint
bighub_constraints_pause	Pause a constraint
bighub_constraints_resume	Resume a constraint
bighub_constraints_dry_run	Preview without persisting
bighub_constraints_validate	Validate an action against constraints
bighub_constraints_validate_dry_run	Validate (dry run)
bighub_constraints_domains	List domains with constraints
bighub_constraints_versions	Constraint version history
bighub_constraints_apply_patch	Apply a JSON Patch
bighub_constraints_purge_idempotency	Admin: purge idempotency keys

---

Approvals & kill switch

Tool	Description
bighub_approvals_list	List approval requests
bighub_approvals_resolve	Resolve an approval
bighub_kill_switch_status	Kill switch status
bighub_kill_switch_activate	Activate kill switch
bighub_kill_switch_deactivate	Deactivate kill switch

---

Events

Tool	Description
bighub_events_list	Query event stream
bighub_events_stats	Event statistics

---

Webhooks

Tool	Description
bighub_webhooks_create	Create a webhook
bighub_webhooks_list	List webhooks
bighub_webhooks_get	Get a webhook
bighub_webhooks_update	Update a webhook
bighub_webhooks_delete	Delete a webhook
bighub_webhooks_deliveries	List deliveries
bighub_webhooks_test	Send a test delivery
bighub_webhooks_list_events	List subscribable event types
bighub_webhooks_verify_signature	Verify webhook signature
bighub_webhooks_replay_failed_delivery	Replay a failed delivery

---

API keys

Tool	Description
bighub_api_keys_create	Create an API key
bighub_api_keys_list	List API keys
bighub_api_keys_delete	Delete an API key
bighub_api_keys_rotate	Rotate an API key
bighub_api_keys_validate	Validate an API key
bighub_api_keys_scopes	List available scopes

---

Auth

Tool	Description
bighub_auth_signup	Create an account
bighub_auth_login	Log in
bighub_auth_refresh	Refresh token
bighub_auth_logout	Log out

---

Utility

Tool	Description
bighub_http_request	Generic HTTP passthrough

---

Environment Variables

Variable	Required	Default	Description
BIGHUB_API_KEY	Yes*	-	API key auth
BIGHUB_BEARER_TOKEN	No	-	Alternative bearer auth
BIGHUB_BASE_URL	No	https://api.bighub.io	API base URL
BIGHUB_TIMEOUT_MS	No	15000	Request timeout
BIGHUB_MAX_RETRIES	No	2	Retries on transient failures
BIGHUB_ALLOW_INSECURE_HTTP	No	-	Allow HTTP for local/private testing

* One of BIGHUB_API_KEY or BIGHUB_BEARER_TOKEN is required.

Management tools (API keys, webhooks, auth) require user JWT auth via BIGHUB_BEARER_TOKEN.

---

Local Development

git clone https://github.com/bighub-io/bighub.git
cd bighub/servers/mcp
npm install
npm run test
npm run check
npm run build
npm run start
npm run dev

---

Links

• bighub.io
• GitHub - bighub-io/bighub
• npm - @bighub/bighub-mcp
• PyPI - bighub (Python SDK)
• PyPI - bighub-openai

---

License

Apache-2.0