docs(signal): clearer MCP consent-screen scopes and per-user authorization - #928
docs(signal): clearer MCP consent-screen scopes and per-user authorization#928saif-at-scalekit wants to merge 1 commit into
Conversation
WalkthroughThe MCP authentication guide now documents standard OAuth scopes, consent-screen behavior, bring-your-own-auth values, and the need for runtime authorization checks in tool handlers. ChangesMCP scope documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
saif-at-scalekit
left a comment
saif-at-scalekit
left a comment
There was a problem hiding this comment.
Leaving two comments.
|
|
||
| **Every sign-in includes a set of standard scopes you cannot remove.** Alongside the custom scopes you define for your server (for example, `todo:read`), a request carries the OpenID Connect scopes `openid`, `profile`, and `email` so the client can identify the user it acts for, plus `offline_access` so Scalekit can issue a refresh token and keep the connection alive without re-prompting the user. These are platform defaults and do not appear as removable options on the consent screen. On a [bring-your-own-auth](/authenticate/mcp/custom-auth/) server, `profile` and `email` expose only the values you send in the user-details handoff — a placeholder email, for example — never data you do not provide. | ||
|
|
||
| **Scopes are not per-user permissions.** A scope reflects what the client requested, not what an individual user is allowed to do, and the consent screen does not currently let a user grant a subset of the requested scopes. Do not rely on consent-time scope selection to enforce per-user access. Instead, enforce authority when a tool runs: check the acting user's role or permission inside each tool handler before executing, and reject the call otherwise. Consent decides what is granted; a runtime check decides what is actually usable. This is the model major identity providers use, and it stays correct when a user's role changes after they first consent. |
There was a problem hiding this comment.
@AkshayParihar33 Do you feel this phrasing is a slightly confusing?
|
|
||
| ## Scopes and the consent screen | ||
|
|
||
| Scopes on an MCP authorization request describe what the **client** — Claude, ChatGPT, Cursor, or your own app — is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. |
There was a problem hiding this comment.
| Scopes on an MCP authorization request describe what the **client** — Claude, ChatGPT, Cursor, or your own app — is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. | |
| Scopes on an MCP authorization request describe what the **client** (Claude, ChatGPT, Cursor, or your own app) is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/docs/authenticate/mcp/overview.mdx`:
- Around line 196-198: Rewrite the scopes explanation in the MCP authorization
overview to use second-person wording throughout, replacing references such as
“the user,” “an individual user,” and “acting user” with “you,” “your
application,” or “your permissions.” Preserve the existing security meaning and
all details about standard scopes, consent, refresh tokens, and
bring-your-own-auth behavior.
- Around line 196-200: The opening description of scopes in the first paragraph
suggests they grant authorization ("is allowed to do"), which contradicts the
clarification later that scopes represent only what the client requests, not
what it is actually permitted to do. Update the wording in the first sentence
where scopes are introduced to describe them as "what the client requests to
access" instead of "is allowed to do," ensuring consistency with the subsequent
explanation that scopes do not grant per-user permissions and that runtime
checks are required for actual access control.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5813e198-d676-46f0-976a-0f07d58bb122
📒 Files selected for processing (1)
src/content/docs/authenticate/mcp/overview.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (13)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/authenticate/mcp/overview.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- Headings that match a real API parameter, method, or field name
(e.g.,contactID,xero_tenant_id,executeTool) should preserve
the original casing. Do NOT flag these as sentence-case violations.- No heading should end with a colon or period.
Content structure
- Journey how-to guides MUST contain numbered
<Steps>(Starlight
component). This does NOT apply tosrc/content/docs/cookbooks/**
(blog-style recipes — optional<Steps>,<Tabs>after</Steps>OK;
see cookbookspath_instructions).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:f...
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
src/content/docs/authenticate/mcp/overview.mdx
src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)
src/content/docs/**/*.mdx: In MDX documentation files,<Steps>must contain one continuous ordered list. Wrap<Steps>around a normal Markdown ordered list such as1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the1. ##,2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images,<Tabs>,<TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside<Steps>. If the content is mostly<Tabs>or other JSX-heavy blocks, use normal section headings instead of<Steps>
In MDX documentation files, when<Tabs>is used inside a step, keep<Tabs>,<TabItem>,</TabItem>, and</Tabs>consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside</Steps>
Files:
src/content/docs/authenticate/mcp/overview.mdx
src/content/**/*.mdx
📄 CodeRabbit inference engine (CONTRIBUTING.md)
src/content/**/*.mdx: All documentation must live as MDX files insidesrc/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js usesscalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/content/docs/authenticate/mcp/overview.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: Every documentation page must include frontmatter withtitle,description, andsidebar.label;titlemust be at most 60 characters,descriptionat most 160 characters, and sidebar labels should be 1–3 words.
Use sentence case for all titles and headings, keep page titles short and descriptive, and make headings describe outcomes rather than categories.
Use H2 for major sections, H3 for subsections, H4 only inside<Steps>, and never use H1 in body content.
Use descriptive link text, prefer relative links for internal pages, and never use labels such asclick hereorthis.
Use fenced code blocks with language identifiers, format technical identifiers with inline code, include table headers, and ensure examples are runnable or clearly marked as placeholders.
Never hard-code secrets or API keys in documentation or code examples; explain relevant security threats and mitigations.
Documentation code examples must use the exact SDK variable names: Node.jsscalekit, Pythonscalekit_client, GoscalekitClient, and JavascalekitClient.
At least approximately 90% of SDK-related code examples must include Node.js, Python, Go, and Java implementations, with consistent naming, success and error paths, and security explanations.
Use<Tabs syncKey="tech-stack">for multi-language SDK samples and include clear language tabs, imports, realistic data, success and error handling, and appropriate Expressive Code features.
When using Starlight<Steps>, keep numbered steps at column 0, indent continuation content and sub-bullets by exactly three spaces, and keep nested<Tabs>blocks inside the owning list item.
Use the primary structure appropriate to each document type: how-to guides include overview, prerequisites, procedure, verification, and optional next steps; API references include endpoint summary, authentication, base URL, parameters, request, response, and errors; concept pages include overview, concepts, use cases, t...
Files:
src/content/docs/authenticate/mcp/overview.mdx
src/**/*.{ts,tsx,astro,md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
Navigation structure changes must be coordinated across
src/configs/sidebar.config.ts,src/components/overrides/Header.astro, andsrc/components/SecondaryNav.astro.
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{ts,tsx,astro,md,mdx,css}
📄 CodeRabbit inference engine (CLAUDE.md)
All changes must pass Prettier formatting, the build, Git hook validations, and content-structure validation; use pnpm, Astro/Starlight conventions, Tailwind CSS compatibility, and Vue 3 and React compatibility.
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{ts,tsx,astro,md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Use Astro + Starlight conventions, maintain Tailwind CSS compatibility, and ensure Vue 3 and React component compatibility.
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Use
pnpmfor package management, and ensure changes pass Prettier formatting, the build, Git hook validations, and content-structure validation.
Files:
src/content/docs/authenticate/mcp/overview.mdx
**/*.{ts,tsx,js,jsx,java,py,go,md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Use JSDoc, JavaDoc, or docstrings for functions, classes, and complex logic; document parameters, return values, types, exceptions, edge cases, useful references, and bug-fix issue links, using standard TODO, FIXME, and NOTE formats.
Files:
src/content/docs/authenticate/mcp/overview.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/mcp/overview.mdx
🧠 Learnings (13)
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-02-25T13:04:27.491Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:9-17
Timestamp: 2026-02-25T13:04:27.491Z
Learning: Allow page-level CSS overrides in MDX frontmatter (head: style) for readability and engagement, even if it customizes typography beyond defaults. This applies to per-page UX decisions, including heading sizes and style tweaks, but keep overrides purposeful, accessible, and within the repository's design guidelines. Use these overrides sparingly and document the rationale for maintainability.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-03-05T11:29:08.125Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 463
File: src/content/docs/agent-auth/providers.mdx:35-73
Timestamp: 2026-03-05T11:29:08.125Z
Learning: In src/content/docs/agent-auth/providers.mdx, the Card components intentionally use icon=" " (a space) to render consistent colored boxes since some Starlight icon names resolve to icons and others do not. Do not flag icon=" " as a placeholder issue for this file; treat this as a deliberate UX choice specific to this MDX page and avoid raising a placeholder-icon warning here.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-03-09T07:27:56.794Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 469
File: src/content/docs/guides/integrations/scim-integrations/azure-scim.mdx:95-107
Timestamp: 2026-03-09T07:27:56.794Z
Learning: Do not enforce the 3-space indentation rule for Steps component content as a hard style rule in MDX files under src/content/docs/**/*.mdx. Only flag/rectify it if it causes visible rendering problems in the UI. Otherwise, allow current formatting; apply this rule only when rendering issues are observed and document any fixes.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-03-09T07:32:38.426Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 467
File: src/content/docs/sso/guides/sso-user-attributes.mdx:108-148
Timestamp: 2026-03-09T07:32:38.426Z
Learning: In MDX code samples under src/content/docs (and similar conceptual snippets in scalekit-inc/developer-docs), when an example's sole purpose is to show how to access a specific value (e.g., reading JWT claims after token validation), omit error/non-happy-path handling to keep the snippet focused. Do not flag the absence of error paths in narrowly scoped conceptual snippets.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.
Applied to files:
src/content/docs/authenticate/mcp/overview.mdx
| Scopes on an MCP authorization request describe what the **client** — Claude, ChatGPT, Cursor, or your own app — is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. | ||
|
|
||
| **Every sign-in includes a set of standard scopes you cannot remove.** Alongside the custom scopes you define for your server (for example, `todo:read`), a request carries the OpenID Connect scopes `openid`, `profile`, and `email` so the client can identify the user it acts for, plus `offline_access` so Scalekit can issue a refresh token and keep the connection alive without re-prompting the user. These are platform defaults and do not appear as removable options on the consent screen. On a [bring-your-own-auth](/authenticate/mcp/custom-auth/) server, `profile` and `email` expose only the values you send in the user-details handoff — a placeholder email, for example — never data you do not provide. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use second-person wording in this section.
The text uses the user, an individual user, and acting user's. Rewrite these phrases as you, your application, or your permissions without changing the security meaning.
As per path instructions, documentation must address the reader in the second person.
Also applies to: 200-200
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/authenticate/mcp/overview.mdx` around lines 196 - 198,
Rewrite the scopes explanation in the MCP authorization overview to use
second-person wording throughout, replacing references such as “the user,” “an
individual user,” and “acting user” with “you,” “your application,” or “your
permissions.” Preserve the existing security meaning and all details about
standard scopes, consent, refresh tokens, and bring-your-own-auth behavior.
Source: Path instructions
| Scopes on an MCP authorization request describe what the **client** — Claude, ChatGPT, Cursor, or your own app — is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. | ||
|
|
||
| **Every sign-in includes a set of standard scopes you cannot remove.** Alongside the custom scopes you define for your server (for example, `todo:read`), a request carries the OpenID Connect scopes `openid`, `profile`, and `email` so the client can identify the user it acts for, plus `offline_access` so Scalekit can issue a refresh token and keep the connection alive without re-prompting the user. These are platform defaults and do not appear as removable options on the consent screen. On a [bring-your-own-auth](/authenticate/mcp/custom-auth/) server, `profile` and `email` expose only the values you send in the user-details handoff — a placeholder email, for example — never data you do not provide. | ||
|
|
||
| **Scopes are not per-user permissions.** A scope reflects what the client requested, not what an individual user is allowed to do, and the consent screen does not currently let a user grant a subset of the requested scopes. Do not rely on consent-time scope selection to enforce per-user access. Instead, enforce authority when a tool runs: check the acting user's role or permission inside each tool handler before executing, and reject the call otherwise. Consent decides what is granted; a runtime check decides what is actually usable. This is the model major identity providers use, and it stays correct when a user's role changes after they first consent. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Describe scopes as requested access, not effective authorization.
Line 196 says scopes describe what the client “is allowed to do.” Line 200 says scopes represent requested access and do not grant per-user permissions. Replace the Line 196 wording with “what the client requests to access” to remove the contradiction.
As per path instructions, consent-time scopes must not replace runtime authorization checks.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/authenticate/mcp/overview.mdx` around lines 196 - 200, The
opening description of scopes in the first paragraph suggests they grant
authorization ("is allowed to do"), which contradicts the clarification later
that scopes represent only what the client requests, not what it is actually
permitted to do. Update the wording in the first sentence where scopes are
introduced to describe them as "what the client requests to access" instead of
"is allowed to do," ensuring consistency with the subsequent explanation that
scopes do not grant per-user permissions and that runtime checks are required
for actual access control.
Source: Path instructions
![prelint[bot]](https://avatars.githubusercontent.com/in/2822344?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
The new section states that offline_access is "always present" as a platform default that "cannot be removed," but troubleshooting.mdx line 59 explicitly instructs developers to add `offline_acces...
src/content/docs/authenticate/mcp/overview.mdx:199
1 finding(s) posted as inline comments.
| Scopes on an MCP authorization request describe what the **client** — Claude, ChatGPT, Cursor, or your own app — is allowed to do. The client requests them, and Scalekit shows them to the user on the consent screen. | ||
|
|
||
| **Every sign-in includes a set of standard scopes you cannot remove.** Alongside the custom scopes you define for your server (for example, `todo:read`), a request carries the OpenID Connect scopes `openid`, `profile`, and `email` so the client can identify the user it acts for, plus `offline_access` so Scalekit can issue a refresh token and keep the connection alive without re-prompting the user. These are platform defaults and do not appear as removable options on the consent screen. On a [bring-your-own-auth](/authenticate/mcp/custom-auth/) server, `profile` and `email` expose only the values you send in the user-details handoff — a placeholder email, for example — never data you do not provide. | ||
|
|
There was a problem hiding this comment.
Caution
The new section states that offline_access is "always present" as a platform default that "cannot be removed," but troubleshooting.mdx line 59 explicitly instructs developers to add offline_access to their authorization request because "Without it, Scalekit does not issue a refresh token alongside the access token." The xmcp-quickstart.mdx scope example (line 501) also omits offline_access from the default scope list ["openid", "profile", "email"]. These three existing documents treat offline_access as opt-in, not mandatory — the new section directly contradicts them and will cause developers to incorrectly assume they always receive a refresh token.
2 participants
Why: A few users asked the same two things about the MCP consent screen — what the default scopes (
profile,offline_access) mean and whether they can be removed, and how to show or enforce per-user permissions when scopes are requested by the client. The MCP docs explained scopes at the OAuth-flow level but never covered the default consent scopes or the scopes-vs-per-user-authority distinction.What: Surgical addition of a short "Scopes and the consent screen" concept section in
src/content/docs/authenticate/mcp/overview.mdx, right after the existing security-enhancements section. It states that the standard identity scopes (openid,profile,email) plusoffline_accessare always present and cannot be removed, notes whatprofile/emailexpose on a bring-your-own-auth server, and explains that scopes reflect what the client requested — so per-user authority should be enforced at tool-execution time, not via consent-time scope selection. Prose only, no code sample. Skills applied: docs-engineering, docs-contribution-router, docs-writing-style.Check: Open
/authenticate/mcp/overview/; confirm a new "Scopes and the consent screen" section appears after "Key security enhancements in MCP OAuth 2.1", with the two bold-led paragraphs on default scopes and per-user authorization.Preview: https://deploy-preview-928--scalekit-starlight.netlify.app/authenticate/mcp/overview/
Generated by Claude Code
Summary by CodeRabbit