> 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.balkanid.app) **OAuth Connectors** section; if you use an API key, confirm it is not expired or revoked. 3. Confirm the client URL is `https://mcp.balkanid.app/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.balkanid.app) / 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; 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; 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 | | Windsurf config path not found | Windsurf/Cascade docs and config location moved under Devin after the rebrand | Use Cascade's own **Configure** button to find the current path rather than an old `~/.codeium/...` path | | Cline: connection errors or wrong transport | `"type"` missing or set to `"sse"` instead of `"streamableHttp"` | Confirm `"type": "streamableHttp"` (camelCase) and the URL in `mcpServers.balkanid` | | Zed: JSON errors after editing settings | A syntax error in `settings.json` disables all of Zed's settings, not just MCP | Validate `settings.json`; re-copy the `context_servers` snippet from OAuth Connectors if unsure | | Codex/ChatGPT Desktop: 401 after it worked before | Stored OAuth token expired without refreshing | Run `codex mcp login balkanid` again, or switch to the API key fallback | | Codex: Bearer token env var not found | The variable isn't set in the shell that launched Codex | Export it in your shell profile and restart Codex | | Codex: project config ignored | A `.codex/config.toml` only loads in trusted projects | Confirm the project is trusted, or use the user-scoped `~/.codex/config.toml` instead | | ChatGPT Desktop: API key not picked up | App launched from Dock/Finder doesn't inherit shell-exported env vars | Restart the app after setting the Bearer token env var; on macOS avoid Dock-only launches when testing | | OpenCode / LibreChat: OAuth never prompts | A static `Authorization` header is still set, or the server isn't marked `enabled` | Remove any leftover Bearer header for the OAuth path; confirm the server entry is enabled in the client's MCP config | | 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 | | 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.