fix(mcp): explain the Claude-side steps after "Anslut till Claude" and tick the checklist on a real connection (#2133) (#2147)

* fix(mcp): explain the Claude-side steps after "Anslut till Claude" and tick the checklist on a real connection (#2133)

Lazy auth is by design: Claude lists the tools before any sign-in and the
first company-scoped call answers 401, which opens the Accounted sign-in.
Nothing told the user, so a "connected" status with an unanswered first
question read as a broken connection (Axel, Discord).

- Settings -> API & MCP: one sentence of expectation under the button, and
  the step-by-step guide link moved from under two disclosures to directly
  under the button.
- Docs (connect-claude / anslut-claude): new "What happens after you click"
  section for Path A covering the connector dialog, the tools appearing
  before sign-in, the first-call login + consent screen, "ask again", and
  the "Required when the server asks" auth setting that only the manual
  path mentioned.
- Hem checklist step "Anslut till Claude": deep link now carries
  client=claude-connector like the settings button (claudeConnectorLink),
  the footnote carries the same expectation line plus the guide link, and
  the done-signal is an unrevoked api_keys row minted by the MCP OAuth
  token route (OAUTH_MCP_KEY_NAME) instead of the in-app AI-profile flag,
  which never meant "connected to Claude".
- Tests: claudeStepDone with/without a key row, deep-link snapshot.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W7iJQwKiRTDWSMnRm4WM4L

* fix(mcp): correct consent-page claims, stop the completion PATCH loop, count OAuth keys past RLS (#2133)

Three skeptic refutations on PR #2147, fixed in one pass:

- Docs (EN + SV): the consent page shows the company active in the app and
  pre-selects every scope for Claude's connector (founder decision
  2026-08-26); it has no company picker and nothing to tick. Steps 3-4 of
  the new section, the "Read-only by default" paragraph above it, the
  sandbox note and the 10-minute test now describe Endast läs under
  Behörigheter instead.
- Checklist completion: users with initial_setup_path NULL (skipped the
  books question, then imported) hit the route's "Välj först hur du vill
  komma igång" 400 and, with saving as an effect dependency, retried it
  forever with a toast. completionPatchBody() records path=migration when
  none was chosen, and a rejected PATCH is not retried within the session.
- hasMcpKey: api_keys' SELECT policy is company-scoped, so the user client
  could not see companyless (NULL company_id) or archived-company keys and
  the step stayed open for the user who had just connected. The head count
  now runs through the service client with an explicit user_id filter.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W7iJQwKiRTDWSMnRm4WM4L

* fix(mcp): surface a failed OAuth-key count and reserve the marker name (#2133)

CodeRabbit round on PR #2147:

- app/(dashboard)/page.tsx: a failed api_keys count answered count null,
  which claudeStepDone read as "never connected". Throw to the error
  boundary like the settings fetch does instead of guessing.
- app/api/settings/api-keys: reject a hand-minted key named
  MCP-klient (OAuth) (400 VALIDATION_ERROR): that name is the marker the
  Hem checklist reads as "connected to Claude", so a manual key with it
  would tick the step without any connection. Test added.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W7iJQwKiRTDWSMnRm4WM4L

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

app/api/mcp-oauth/token/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { decryptAuthCode, verifyPkce, hashAuthCode } from '@/lib/auth/oauth-codes'
 import {
   generateApiKey,
+  OAUTH_MCP_KEY_NAME,
   generateRefreshToken,
   hashRefreshToken,
   createServiceClientNoCookies,
@@ -161,7 +162,7 @@ async function handleAuthorizationCodeGrant(params: URLSearchParams) {
       company_id: companyId,
       key_hash: hash,
       key_prefix: prefix,
-      name: 'MCP-klient (OAuth)',
+      name: OAUTH_MCP_KEY_NAME,
       scopes: grantedScopes,
       refresh_token_hash: refresh.hash,
     })

app/api/settings/api-keys/__tests__/route.test.ts

@@ -108,6 +108,24 @@ describe('POST /api/settings/api-keys', () => {
     expect(body.error.code).toBe('API_KEY_SCOPE_INVALID')
   })
 
+  it('returns 400 for the reserved OAuth marker name (would fake a Claude connection)', async () => {
+    const { insertSpy } = setupFrom({ count: 0 })
+    const res = await POST(
+      createMockRequest('/api/settings/api-keys', {
+        method: 'POST',
+        body: { name: ' MCP-klient (OAuth) ', scopes: ['reports:read'] },
+      }),
+      { params: Promise.resolve({}) },
+    )
+    const { status, body } = await parseJsonResponse<{
+      error: { code: string; details: { field: string; reason: string } }
+    }>(res)
+    expect(status).toBe(400)
+    expect(body.error.code).toBe('VALIDATION_ERROR')
+    expect(body.error.details).toMatchObject({ field: 'name', reason: 'reserved' })
+    expect(insertSpy).not.toHaveBeenCalled()
+  })
+
   it('returns 409 API_KEY_SOD_CONFLICT for stage+approve without acknowledgement', async () => {
     setupFrom({ count: 0 })
     const res = await POST(

app/api/settings/api-keys/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import {
   generateApiKey,
   DEFAULT_SCOPES,
+  OAUTH_MCP_KEY_NAME,
   validateScopes,
   findStageApproveConflict,
 } from '@/lib/auth/api-keys'
@@ -68,6 +69,17 @@ export const POST = withRouteContext(
       // Empty body: use defaults.
     }
 
+    // The OAuth token route's key name is the marker the Hem checklist reads
+    // as "connected to Claude" (there is no source column). A hand-minted key
+    // with that name would tick the step without any connection, so the name
+    // is reserved for the OAuth path.
+    if (name.trim() === OAUTH_MCP_KEY_NAME) {
+      return errorResponseFromCode('VALIDATION_ERROR', log, {
+        requestId,
+        details: { field: 'name', reason: 'reserved', reserved: OAUTH_MCP_KEY_NAME },
+      })
+    }
+
     // Both live and test keys bind to the active company. A test key is
     // simulation-only (the v1 wrapper forces dry-run on every write) so it can
     // safely point at the real company without ever persisting anything.