read thedocs.

[ docs // guides & reference ]

Connector setup guides, tool references, auth flows, and platform concepts — everything you need to run StackJack, in one place.

Browse the Docs All Connectors
34 connectors documented // 6,712 tools referenced // setup, auth & platform guides
↓

No pages match that search. Clear it

← All documentation

Connectivity & Health Checks

When something isn't working, the first job is figuring out which layer is broken: the network path to StackJack, your AI tool's connection, or a connector's credentials. StackJack gives you a check for each layer, and none of them require waiting on support.

Layer 1: Is StackJack reachable? (/health)

The MCP server publishes a public, unauthenticated health endpoint:

https://mcp.stackjack.io/health

Open it in a browser or run curl https://mcp.stackjack.io/health from any machine. It returns HTTP 200 with Healthy when the service and its dependencies (database and cache) are ready, and an unhealthy status otherwise. A companion endpoint, /alive, answers whether the service process itself is up, independent of its dependencies.

The portal exposes the same endpoints at https://portal.stackjack.io/health and /alive.

How to read the results:

Result Meaning
/health returns Healthy but your AI tool can't connect The network is fine — the problem is the AI tool's authentication or MCP configuration. See Your MCP endpoint.
/health doesn't respond from your network but does from elsewhere (for example, a phone off Wi-Fi) Your firewall or proxy is blocking the path.
/health returns unhealthy or doesn't respond from anywhere A platform-side issue. Check for advisories (below) or contact support.

Layer 2: Is my session healthy? (ask your AI)

Any connected AI assistant can diagnose its own session using StackJack's built-in platform tools — these work even when no connector is configured yet.

stackjack_session_info — the "who am I and what do I have" check. Returns your workspace and client identity, each active connector with its plan, monthly call limit, and whether credentials are present, plus how many tools are accessible to this session. If a new team member's harness connects before an admin has assigned them tools, this returns a clear pending_approval status telling them exactly what their admin needs to do.

stackjack_health_check — live connectivity test. For every configured connector it validates the stored credentials against the vendor API right now and reports status, latency in milliseconds, and error detail per connector (a connector whose stored credentials can't be loaded this request is reported as unavailable and retryable rather than being probed). Pass an optional connector filter to test just one connector instead of all of them. If your workspace has nothing configured, the response is a no_connectors status pointing you to the portal.

stackjack_get_service_status — StackJack's own status: overall platform state, per-component status, and any advisories that apply to your workspace or connectors (for example, a known vendor API incident). stackjack_list_advisories gives the filterable list. There is no separate public status page — this is the status surface, available to every connected assistant.

A practical opener when anything misbehaves:

"Run stackjack_session_info and stackjack_health_check and summarize what's wrong."

Layer 3: Are my connector credentials working? (the portal)

The Connectors page shows a live health badge on every configured connector — Valid, Invalid, or Disabled. An Invalid (but still enabled) card shows a warning with the error and a Re-test button for an immediate re-validation; a Disabled card shows a keyboard-accessible "Why?" tooltip with the specific reason, the full error alert, and Re-enable + Update Credentials recovery buttons.

StackJack also re-validates every connector automatically about every half hour, and auto-disables a credential after three consecutive definitive failures, emailing the workspace owner with a plain-language explanation and recommended fix. The full behavior — health states, the three-strike rule, and recovery steps — is documented in Connector Health & Auto-Disable.

Putting it together: a quick triage flow

  1. curl https://mcp.stackjack.io/health → not Healthy? Platform or network issue; check advisories or support.
  2. AI tool won't connect but /health is fine → credentials/config in the AI tool; see Authentication options.
  3. Connected, but tool calls fail → ask the AI to run stackjack_session_info (pending approval? missing credentials?) and stackjack_health_check.
  4. One connector failing → portal → Connectors → check the badge; if it's Invalid, hit Re-test; if it's Disabled, follow the card's recovery guidance.
  5. Still stuck → the error your AI received contains a correlationId — quote it to support, or let the AI open a prefilled ticket. See Error & Support Code Reference.