docs(gmail): gmail.settings.basic required for filter tools (#385)

[iShark5060]

Fixes #385.

This does not stop create_filter / list_filters 403s by itself. Gmail connector OAuth is not declared in this repo, so there is no in-repo scope list to add gmail.settings.basic to. Documenting that, plus the re-consent step, is the change this plugin can make.

What we checked

The Gmail plugin is a URL wrapper:

{
  "mcpServers": {
    "gmail": {
      "type": "http",
      "url": "https://gmailmcp.googleapis.com/mcp/v1"
    }
  }
}

No auth.CLIENT_ID, no auth.scopes. Contrast with third_party/x/mcp.json, which can add dm.read / dm.write because it ships X's static client ID.

Google Workspace plugins in this repo follow the same pattern (Gmail / Drive / Calendar): packaging only. Cursor's first-party Google client (MCP_OAUTH_PROVIDER_POLICIES / cursor-gws-prod consent screen, per #345) owns OAuth. Adding a fake auth block without that client ID would either be ignored or break Google sign-in (CLIENT_ID is required when auth is present).

Live evidence

1. Reproduced list_filters against this connector: HTTP MCP tool execution failed: Streamable HTTP error: Server returned 403 after trying upscoping — same error as Gmail plugin: create_filter / list_filters fail with 403 — OAuth missing gmail.settings.basic #385.

2. Google's protected-resource metadata already advertises the missing scope:

   GET https://gmailmcp.googleapis.com/.well-known/oauth-protected-resource/mcp/v1

   scopes_supported includes https://www.googleapis.com/auth/gmail.settings.basic (alongside gmail.readonly, gmail.modify, gmail.compose, etc.).

3. Gmail API filters.create requires only gmail.settings.basic. gmail.modify covers labels/messages, which is why those tools work while filters do not. Linked Apps “See (but not change) your email settings” is gmail.readonly, not settings write.

4. Unauthenticated tools/list on gmailmcp.googleapis.com/mcp/v1 omits filter tools; the authenticated Cursor/Grok session exposes create_filter / list_filters / update_filter / delete_filter. Tools have no per-tool scope annotations, so upscoping cannot learn settings.basic from tools/list.

What still must change outside this repo

1. Google Cloud consent screen for Cursor's Gmail/Workspace OAuth client: add https://www.googleapis.com/auth/gmail.settings.basic under Data Access. This scope is sensitive; it may need Google restricted-scope verification.
2. Connector OAuth request / upscoping: ensure the token request actually includes that scope. Today's “403 after trying upscoping” plus Linked Apps never showing settings write means upscope is not obtaining settings.basic (hardcoded subset and/or consent screen omission). Do not request https://mail.google.com/ just to make filters work.
3. Existing users must disconnect the Gmail plugin and sign in again after (1)+(2). Re-auth without a new scope does not help (also reported in Gmail plugin: create_filter / list_filters fail with 403 — OAuth missing gmail.settings.basic #385).

This PR

• README: filter-tool scope, why mcp.json cannot request it, re-consent.
• Changelog + plugin version 1.0.1.

No mcp.json auth block on purpose.

Test plan

• Reproduced list_filters 403 after upscoping on the live Gmail MCP
• Confirmed PRM scopes_supported includes gmail.settings.basic
• Confirmed third_party/gmail/mcp.json has no OAuth scopes/client ID (Drive/Calendar match)
• After the out-of-repo client/consent change: Linked Apps shows “See, edit, create, or change your email settings and filters”; reconnect Gmail; list_filters / create_filter succeed