Troubleshooting
Match the symptom, apply the fix. Problems fall into two kinds: connection errors, where the assistant can't reach the tools at all, and tool errors, where one call fails with a message. Every tool is read-only, so none of these leave anything half-changed.
5 Sections
Jump to a section below.
Forward the exact message
Refusals caused by an administrator's settings name the setting. Send the exact message to your StratoLens administrator.
Setup
Allow MCP connections is grayed out
Answer
Turn on Allow external API access first. If it is already on, you lack Modify Settings and Manage Roles; ask an Administrator.
I can't see the MCP server URL
Answer
It appears only after Allow MCP connections is saved on. If a message about no public base URL appears in its place, StratoLens has no public address configured; contact StratoLens support.
I can't see Add client
Answer
The Trusted clients table and its Add client button appear only after Allow external API access has been saved on.
Sign-In and Connection
VS Code shows Need admin approval, then waits for the server to respond
Answer
The VS Code client is not pre-authorized, so Entra blocks the sign-in before StratoLens sees a request. An administrator adds the VS Code (GitHub Copilot) preset. Don't grant tenant-wide admin consent instead: it gets past Entra, but StratoLens still refuses a client that is not on the Trusted clients list.
VS Code logs "retrying with new auth registration" or "Cannot force new registration"
Answer
That is how VS Code reacts to any refusal, and it is harmless. Read the error message VS Code shows and find it on this page.
Claude, Claude Code or ChatGPT sign-in fails with AADSTS9010010
Answer
The full message reads "The resource parameter provided in the request doesn't match with the requested scopes". The MCP server URL is not an Application ID URI of the StratoLens App Registration. Re-run the client's script from Add Trusted Client, or add the URL on the Manifest blade, keeping api://<stratolensClientId>. While it is missing, the Security card shows a warning under the MCP server URL.
Verify says the MCP server URL is missing
Answer
The script or the Manifest step did not run, or Entra hasn't caught up yet. Wait a minute and click Verify and add again.
The client keeps asking me to sign in, or reports Authentication failed
Answer
The client sent no sign-in, or an expired or wrong one. It follows the discovery pointer and signs you in again. App-only sign-ins (service principals, managed identities) are always rejected; MCP needs a signed-in user.
The client can't find where to sign in
Answer
If the discovery document returns an error, StratoLens has no public address configured. Contact StratoLens support.
The URL in my client differs from the Security card
Answer
Use the Security card value. If the Security card shows a different host than the one users reach StratoLens on, contact StratoLens support.
Refused by StratoLens
These messages come from StratoLens's own settings, before any tool runs. The first three are checked in the order listed, so you see the first one that applies.
"External API access is disabled by your StratoLens administrator."
Answer
The master switch is off. An administrator turns on Allow external API access (see Setup).
"Client <id> is not a trusted client for this StratoLens installation."
Answer
The client app is not on the Trusted clients list. An administrator adds it with Add client; the ID in the message is the one to add.
"MCP connections are disabled by your StratoLens administrator."
Answer
An administrator turns on Allow MCP connections.
"Your StratoLens administrator has not granted you external API access."
Answer
Restrict API access to granted users is on and your grant lacks External API access. An administrator turns it on in your grant on Settings > Users.
"The MCP endpoint accepts external_read tokens only."
Answer
A StratoLens browser sign-in was sent instead of an MCP client sign-in. Connect through an MCP client that signs in via a trusted client app.
Tool Errors
A failed tool call returns a message the assistant usually passes on. The Tool Reference lists every message with its error code.
A tool error never means "no data"
When a tool fails it says why. An empty list is returned only when there truly is nothing to show.
"Missing permission data.read" (or another permission)
Answer
Your role lacks the permission that tool needs. Ask an administrator for a role that has it, and ask the assistant to run whoami to list what you have. The permission table maps each ID to its name in StratoLens.
"Rate limit of 60 tool calls per minute reached. Retry in 23 s."
Answer
Wait for the time shown, or ask an administrator to raise Tool calls per minute. Rejected calls count too, so an assistant that keeps retrying stays limited until the minute ends.
"The tool did not finish within 60 s."
Answer
Ask for a shorter time window, more filters or fewer rows per page, then retry.
"Result is 240 KB, over the 200 KB budget."
Answer
Ask for fewer rows per page and let the assistant page through, or add filters.
"No completed scan exists yet" or "Scan not found"
Answer
On a fresh install, run a scan in StratoLens first. For "Scan not found", the assistant used an unknown scan ID; ask it to pick one from list_scans.
"Input validation error" or another message about the arguments
Answer
The assistant passed an unknown argument, an out-of-range value or a conflicting combination, such as "Pass baseScanId or since, not both." or "time window must not exceed 366 days". The message says what to change; ask the assistant to follow it.
"Your data scope could not be resolved, so no data can be returned."
Answer
StratoLens could not work out which subscriptions you may see, so it returns nothing by design. Contact StratoLens support.
"The tool failed unexpectedly."
Answer
Retry, or narrow the query. If it was a "what changed" question, ask the assistant to retry without the "changed by" lookup (includeAttribution false). If it keeps failing, contact StratoLens support.
Answers and Results
The assistant's numbers differ from the page
Answer
- Check the page's filters: it may have a filter or saved view applied.
- Make sure the page shows the same scan.
- After changing an ignore rule or a group membership, wait 2 minutes and ask again.
- Raw change events never match the Changes page, because they are not filtered by ignore rules. Ask about changes between scans instead (see Answers Match the Pages).
It doesn't know about a change I just made
Answer
Every answer, including change events and the activity log, covers only up to the latest scan. Run a scan, then ask again.
Rows repeat or go missing while paging
Answer
The data changed while the assistant was paging, for example a scan finished part-way through. Ask it to start again from the first page.
The assistant says it can't change something
Answer
Every tool is read-only. Make the change in the StratoLens web app or in Azure.