Chapter 13 · Operate
Troubleshooting
When something breaks, the HTTP status code usually tells you which box in the architecture to look at. Start with the decision tree, then use the symptom-cause-fix table for specifics.
🎯 What you'll be able to do
- Use status codes to localise a failure to one component
- Diagnose the most common 401, 403, origin, and payload errors
- Recognise the 'no tools listed' connector problem
Decision tree
Start at the top with the status code or symptom, then follow the branch to the likely cause and fix.
Loading diagram…
Why status codes matter
A
401 means “who are you?” (authentication) — the token problem. A 403 means “I know who you are, but no” (authorization) — either the gateway didn't trust the call, or Jira denied the user. Telling them apart saves hours.Symptom · cause · fix
| Symptom | Likely cause | Fix |
|---|---|---|
/mcp | Missing or malformed bearer token | Reauthenticate the connection; verify the Authorization header reaches APIM. |
/mcp 403 gateway error | App didn't receive correct X-Gateway-Token | Call through APIM; verify the Key Vault named value resolved; verify the app setting. |
| Origin blocked | Origin not in ALLOWED_ORIGINS | Add the correct Copilot Studio / Power Platform origin; never use wildcard in production. |
| Jira returns 403 | User lacks permission or wrong site selected | Verify Jira project permissions; pin JIRA_SITE_URL if needed. |
| No tools listed in Copilot Studio | Connector imported as REST or MCP extension missing | Reimport mcp-connector.swagger.json and preserve x-ms-agentic-protocol. |
| Atlassian sign-in fails | Redirect URI mismatch | Match the Atlassian callback URL to the Power Platform connector redirect URL. |
| Token refresh fails | Missing offline_access | Add the scope to the Atlassian app and the connector. |
AsyncResponsePayloadTooLarge | Response budget too high or tool returns too much | Lower MAX_RESPONSE_BYTES and MAX_RESULTS_CAP; trim fields more aggressively. |
| Local server starts but Jira calls fail | No real Atlassian token | Use a Copilot Studio connection or supply a valid short-lived token for tests. |
| APIM deploy succeeds but calls fail | Placeholder IP filter still active | Replace or temporarily remove REPLACE_START_IP / REPLACE_END_IP. |
| Container does not start | Wrong image, port, or dependency issue | Check App Service / Container Apps logs; verify PORT and WEBSITES_PORT. |
❓ Concept check
Calls through APIM return 403 with a gateway message, but the app's own /healthz is fine and a direct call to the app host (bypassing APIM) actually works. What does this tell you?
📌 Chapter summary
- 401 → token; 403 → gateway secret or Jira permission.
- No tools → connector imported as REST (missing MCP extension).
- Payload errors → lower
MAX_RESPONSE_BYTES/MAX_RESULTS_CAPand trim harder.