> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/troubleshooting.md). # Troubleshooting ### Quick checks 1. Confirm MCP is enabled for your tenant. 2. Prefer re-running OAuth from the [MCP UI](https://mcp.app.balkan.id) **OAuth Connectors** section; if you use an API key, confirm it is not expired or revoked. 3. Confirm the client URL is `https://mcp.app.balkan.id/server/mcp`. 4. For API keys, confirm the Authorization header uses `Bearer` plus the full token from the MCP UI. 5. Ask the assistant to call `whoami`. If that fails, fix auth before trying other tools. ### Common issues | Issue | Likely cause | What to try | | ----------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 Unauthorized | Missing/invalid OAuth session, or expired/revoked API key | Reconnect via OAuth, or create a new key in the [MCP UI](https://mcp.app.balkan.id) / Employee API Keys and update the client | | MCP disabled / tenant access error | MCP not enabled for the tenant, or wrong tenant selected | Contact BalkanID support or your admin to enable MCP; reconnect and select the correct tenant | | Tool missing from the assistant | Scope or role does not allow that tool | Check [Authentication and Permissions](/balkanid-mcp/authentication-and-permissions.md); use Write scope and/or a higher role if appropriate | | Can list but cannot approve / sync / create | Read-only API key, or role too low | Add **Write** scope (API key) or use OAuth (both scopes); ensure your BalkanID role allows the action | | Expected Read-only OAuth | OAuth does not support partial scopes yet | Use a Read-only API key until partial OAuth scopes are available | | Cursor / VS Code will not connect | Wrong URL, OAuth incomplete, or server disabled in the client | Re-run **Connect to Cursor / VS Code** from OAuth Connectors; enable the server in client MCP settings | | Claude Desktop does not show MCP tools | Config file not saved, Claude not fully restarted, or Node.js missing for `mcp-remote` | Re-paste config from **Connect to Claude**; fully quit and reopen Claude; install Node.js 18+ | | Claude Code managed config ignored | `managed-mcp.json` not at the system path, or wrong permissions | Confirm the path from [Enterprise Rollout](/balkanid-mcp/enterprise-rollout.md); run `claude mcp list` on a managed machine | | OAuth connector fails mid-login | Incomplete consent, wrong tenant, or session issue | Retry the connector flow; confirm you select the correct tenant; fall back to an API key if needed | | Microsoft Teams: cannot upload agent zip | Custom apps blocked by Teams policy | IT admin: enable **Upload custom apps** under Teams **Setup policies** — see [Microsoft Copilot setup](/balkanid-mcp/installation-and-setup/microsoft-copilot.md) | | Microsoft Teams / Copilot: OAuth consent fails | Wrong tenant, incomplete consent, or redirect/DCR misconfiguration | Retry connection manager; select the correct BalkanID tenant; confirm MCP is enabled; start a new chat | | Microsoft Teams / Copilot: 403 Forbidden | Expired OAuth session or insufficient role/scope | Re-authorize in Connection Manager; confirm your BalkanID role; start a new chat | | Microsoft Copilot: agent missing from @ mention | Index delay after upload | Open **BalkanID** from the Teams app list; restart Teams desktop | | Microsoft Teams: personal account | Signed in with a personal Microsoft account | Use your **corporate** Microsoft Entra ID work account | | Tool call times out | Slow upstream query or client timeout too low | Narrow filters; increase the client MCP timeout; retry | ### Verify with whoami and help Ask your assistant: * “Call whoami on BalkanID MCP.” * “Call help on BalkanID MCP.” `whoami` confirms identity and tenant. `help` confirms which tools your connection can see and whether dependent services are healthy. ### Still stuck? Contact or your BalkanID customer success representative. Include: * AI client name and version (Cursor, VS Code, Claude Desktop, Claude Code, …) * Whether you use OAuth or an API key * Approximate time of the failure * The error message (without pasting the secret token) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.balkan.id/balkanid-mcp/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.