Outcomes
Tool invoke statuses
cortexhub_invoke_tools returns a result per call. Common status values:
| Status | Meaning |
|---|---|
ok | Tool ran and returned a result |
awaiting_user_consent | End-user must approve. Poll the MCP Task; optionally cortexhub_request_consent. |
awaiting_operator_approval | Operator must approve. Poll the MCP Task until complete. |
policy_denied | Access rules blocked the call |
step_up | Step-up re-verification required (placeholder; interactive sessions only). Treat like an approval-style park: poll the MCP Task until terminal. |
tool_error | Validation or tool failure (see error and message) |
upstream_provider_error | Connected provider rejected the call |
connection_required | Toolkit not connected for this agent. Share connect_required.portal_url with the user so they connect in CortexHub, then retry. |
connection_unhealthy / connection_expired / connection_disabled | Admin action required; relay the admin guidance from message/details. |
tool_error with error: VALIDATION_ERROR means required arguments were missing or empty in calls[].arguments (not a provider failure). Load schemas first and put every required field inside arguments.
Failed calls also include details.attempted_call with the tool_name, rationale, raw arguments, and arguments_formatted (pretty-printed JSON) so the agent can see exactly what it tried to do. Credential and adapter failures surface the underlying message and error code (for example CREDENTIAL_REFRESH_FAILED) instead of a generic "Dispatch failed".
Every cortexhub_invoke_tools call and every cortexhub_request_consent call must include presentation (headline + sections[]). Omitting it returns error: PRESENTATION_REQUIRED with details.example_email and details.next_step.
When status is awaiting_user_consent or awaiting_operator_approval, the per-call result includes an mcp_task block with task_id. Call cortexhub_get_task until terminal is true. For awaiting_user_consent only, mcp_task may also include approval_id so you can call cortexhub_request_consent for an explicit consent card. For awaiting_operator_approval, call cortexhub_get_task only. Do not call cortexhub_request_consent and do not ask the user to approve in chat or open the CortexHub portal. Operator approvals never expose operator routing (Slack channel ids, webhook targets, or other backoffice delivery metadata). See Meta-tools → cortexhub_request_consent.
When status is connection_required, the per-call result includes a connect_required block with portal_url. For a member-authenticated client, share that link so the member connects the toolkit once in CortexHub Cloud, then retry. For an Org Agent, an org admin must configure the organisation-shared credential before retrying. See Where toolkit access is configured.
Agent instructions
Use CortexHub for all external actions: search_tools → get_tool_schemas → invoke_tools.
Use tool_name from search; pass the same values to get_tool_schemas names[].
Put required schema fields inside calls[].arguments, not next to tool_name.
Never call downstream tool names on tools/call directly.
When a call parks for approval, call `cortexhub_get_task` with `mcp_task.task_id` until `terminal` is true.
For awaiting_user_consent only, optionally call cortexhub_request_consent with
mcp_task.approval_id for an explicit card.
For awaiting_operator_approval, poll only, never call cortexhub_request_consent
and never ask the user to approve in chat or open the CortexHub portal.
When connection_required, share connect_required.portal_url with the user so
they connect the toolkit in CortexHub Cloud, then retry search and invoke.
Treat policy_denied as a terminal outcome.
MCP authentication errors
| Symptom | Likely cause | Fix |
|---|---|---|
401 on /v1/mcp (OAuth path) | Expired access token | Re-open the session with refresh=True |
401 with invalid bearer (OAuth path) | Wrong or revoked client | Check client id/secret |
401 on /v1/mcp (agent-key path) | Wrong or revoked key | Check the agent API key |
400 missing end-user subject (agent-key path) | No X-CortexHub-End-User-Subject | Pass end_user_subject= to session() |
| Missing agent | No X-CortexHub-Agent | Pass agent= to session() |
SDK setup errors
| Symptom | Fix |
|---|---|
ConfigurationError | Set CORTEXHUB_API_KEY, or CORTEXHUB_CLIENT_ID and CORTEXHUB_CLIENT_SECRET |
| Token request fails (OAuth path) | Confirm the MCP OAuth client exists under Account → MCP API access |