How it works
End-to-end flow
Connect
OAuth sign-in from your app or SDK session.
Search
Agent finds tools via cortexhub_search_tools.
Policy
Group rules run before any downstream call.
Invoke
Permitted calls reach Slack, Jira, and others.
Audit
Spans and receipts recorded in CortexHub Cloud.
This flow covers external AI clients and SDKs connecting through the gateway. A member's hosted co-worker runs the same governed discovery and invoke internally, under the same rules. See Agents.
1. Connect
Your AI app or SDK authenticates to https://mcp.cortexhub.ai/v1/mcp with the credential that matches its runtime: interactive clients use Member OAuth Authorization Code + PKCE; server-side processes use a programmatic Member Credential or an organisation gateway key. See Choose your authentication model.
CortexHub creates a gateway identity (agent) for your user and app at connect time.
2. Discover tools (meta-tools)
The gateway exposes five agent meta-tools for discovery, invoke, task poll, and consent. When a call needs approval, CortexHub creates an MCP Task and returns mcp_task.task_id on the parked invoke result. Agents poll with cortexhub_get_task until terminal is true.
| Meta-tool | Purpose |
|---|---|
cortexhub_search_tools | Find tools by intent (tool_name, summary, description per hit) |
cortexhub_get_tool_schemas | Load parameters_schema for chosen tool_name values |
cortexhub_invoke_tools | Run one to ten governed calls (returns an MCP Task when parked) |
cortexhub_get_task | Poll a parked MCP Task until terminal is true |
cortexhub_request_consent | Optional explicit consent card when task inputRequests are not enough |
When a call parks for end-user approval, the per-call result includes mcp_task.task_id. Interactive clients show consent via task inputRequests; others may call cortexhub_request_consent with mcp_task.approval_id.
When a call needs a toolkit connection, the per-call result carries connect_required.portal_url. Share that link with the user; after they connect in CortexHub, retry search and invoke.
When a call needs operator review, poll the MCP Task until it completes. Operators decide in the configured Slack channel or webhook.
The agent loop is:
- Search:
cortexhub_search_toolsreturnsresults[].tool_name,results[].summary, andresults[].description, plusnext_step. - Schemas:
cortexhub_get_tool_schemaswith thosetool_namevalues. - Invoke:
cortexhub_invoke_toolswithcalls[].tool_name,calls[].arguments,calls[].rationale, andcalls[].presentation. - Parked calls: call
cortexhub_get_taskwithmcp_task.task_iduntilterminalis true. Optionally callcortexhub_request_consentfor an explicit consent card or browser link. - Toolkit connect: share
connect_required.portal_url, then retry from step 2.
Each meta-tool response includes a next_step string when the agent should continue.
See Meta-tools for full request and response shapes.
3. Invoke with governance
Each cortexhub_invoke_tools call is resolved against the layered policy that applies to it (the organisation floor, your groups, and any member rules) and the tool's safety profile (read, write, or destructive). The result is a single base decision (permit, require approval, or deny), with optional obligations on top: the call may also store a redacted record and require re-authentication first. The strictest gate wins. Outcomes include:
| Status | Meaning |
|---|---|
ok | Tool ran successfully |
awaiting_user_consent | End user must approve. Client polls the MCP Task; optionally cortexhub_request_consent. |
awaiting_operator_approval | Operator must approve outside the chat. Poll the MCP Task until complete. No in-chat consent UI. |
agent_toolkit_required | Toolkit not connected. Share connect_required.portal_url, then retry. |
autonomous_consent_required | Autonomous run blocked until the member approves on a configured personal channel |
policy_denied | Access rules blocked the call |
step_up | Additional verification is required |
tool_error | The tool or upstream provider failed |
Treat policy_denied, awaiting_user_consent, and awaiting_operator_approval as normal states, not opaque errors.
4. Audit and observability
Permitted and denied calls produce spans, audit events, and receipts admins can review. Optional telemetry webhooks export events to your SIEM or data warehouse.