Copilot Studio's sharp edges: scope claims and character budgets

Two Copilot Studio constraints cost me real hours this sprint; both are cheap to avoid once named.

The three-way scope mismatch. Getting a custom MCP connector authenticating end-to-end took the better part of two days, and nearly all of it came down to three configuration surfaces that must agree on one string: the scope defined under Expose an API on the Entra app registration, the scope Copilot Studio's connector actually requests (and therefore the scp claim inside the token it sends), and the scope your server is configured to require. Any two can match while the third quietly disagrees — the docs I'd accumulated across the project contradicted each other on the name, which is how the disagreement crept in. The debugging move that ends it: decode the token and read the claim first. Paste the access token into a JWT decoder and look at scp and aud before touching any settings — five minutes of looking beats hours of changing things on a guess. Entra's own docs are clear that authorization rides on the scp claim the token actually carries, not on what any portal field says it should carry.

Then normalize. My architecture doc had invented a perfectly reasonable scope name; nothing was mechanically wrong with it, but three surfaces disagreed on it. Renaming to access_as_user — the convention Microsoft's own samples and wizards use — and applying it identically in the registration, the connector, and the server config ended the entire class of bug. The name is cosmetic; the agreement is everything. (Copilot Studio has since added an MCP onboarding wizard, but it prompts for the same client ID, scope, and token URLs — the nicer UI doesn't retire the bug.)

The 8,000-character ceiling. Agent instructions have a hard limit — 8,000 characters, per the documented Copilot Studio limits, still current as I update this — and it's load-bearing. I hit it consolidating three overlapping instruction drafts (a help-desk voice, a data-answering voice, and tool-routing rules) into one agent. The forced discipline was useful: directives survive, explanations don't. Worked examples, background, and reference material moved to knowledge sources; what stayed was behavior — when to call the tool, how to state numbers, what never to do. Anything procedural that won't fit in 8,000 characters probably wasn't behavior in the first place.

Treat both as design inputs rather than surprises and Copilot Studio integration goes from mysterious to merely fiddly.