Raise HTTP 403 with insufficient_scope instead of tool/prompt not found on scope failure

[Copilot]

When an authenticated request lacks the required OAuth scopes, the server was returning a JSON-RPC RESOURCE_NOT_FOUND error ("Tool X not found"). This prevents MCP clients from distinguishing a missing resource from an authorization failure and blocks the OAuth 2.1 step-up flow.

Changes

• InsufficientScopeError — new exception (not a ServerError subclass) carrying required_scopes; propagates through the transport layer rather than being swallowed as a JSON-RPC error
• server.py — call_tool / get_prompt now raise InsufficientScopeError instead of ToolNotFoundError/PromptNotFoundError when the resource exists but scope check fails
• _transport_http.py — catches InsufficientScopeError in _process_messages and sends HTTP 403 Forbidden with {"error":"insufficient_scope"}; AuthErrorMiddleware then adds the WWW-Authenticate header
• _stdio_transport.py — catches InsufficientScopeError and falls back to a JSON-RPC RESOURCE_NOT_FOUND error with required scopes in the description (STDIO doesn't use OAuth per the MCP spec)
• middleware.py — AuthErrorMiddleware now sets error="insufficient_scope" in WWW-Authenticate on 403 responses (was null previously), satisfying RFC 6750

Before / After

# Before: authenticated user, missing scope → 200 with JSON-RPC error
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32002, "message": "Tool private_tool not found"}}

# After: 403 Forbidden
{"error": "insufficient_scope"}
# WWW-Authenticate: ******"insufficient_scope", resource_metadata="..."

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• releases.astral.sh
  • Triggering command: /home/REDACTED/.local/bin/uv uv sync (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.