Troubleshooting

Quick checks

1. Confirm MCP is enabled for your tenant.

2. Prefer re-running OAuth from the MCP UI 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 / 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
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 [e-mail] 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)