[yan-ad]

Summary

• explain that Figma rejects Crabcode during dynamic client registration before browser OAuth
• link Figma approval guidance and desktop MCP fallback
• provide generic guidance for other providers returning registration HTTP 403

Tests

• cargo fmt --check
• cargo test mcp:: --bin crabcode (58 passed)

[Blankeos]

fix/mcp-figma-registration-guidance → main
Model: claude-sonnet-5-5, effort unknown

Confidence: 4.5/5

Small, self-contained error-message change on the OAuth registration path. It reproduces against the real Figma server and the tests cover the matching rules.

Checks run:

• cargo fmt --check: clean
• cargo test mcp:: --bin crabcode: 58 passed
• Built the PR head and ran crabcode mcp auth figma against the real https://mcp.figma.com/mcp: Figma returns HTTP 403 Forbidden: Forbidden at registration and the new guidance prints (screenshot below).
• Ran crabcode mcp auth design against a local mock server that returns 403 on /register: the generic guidance prints, with no Figma wording (screenshot below).
• Both Figma doc links return 200. oauth: false and oauth.clientId are real config keys (src/config/configuration.rs).
• cargo clippy -D warnings fails with 137 errors across the repo (e.g. app.rs, chat.rs). The only hit in oauth.rs is line 384, which this PR doesn't touch.

Confidence bumps:

• The TUI dialog (/mcp → Reauthenticate) uses the same authenticate_with_url_action path and renders err.to_string(), but I didn't drive it to see how the multi-line message wraps. Checking that → 5/5.

Summary

When dynamic client registration gets HTTP 403, the error now says what happened and what to do. For mcp.figma.com it points to Figma's client-approval page and the desktop MCP fallback (http://127.0.0.1:3845/mcp, oauth: false). For any other server it suggests pre-registered oauth.clientId / clientSecret. Other registration failures keep the original message.

Figma (real server)

Other provider (mock server)

Map

flowchart LR
  A[authenticate_with_url_action] -->|register_client fails| B[registration_error]
  B -->|403 + mcp.figma.com| C[Figma guidance]
  B -->|403 + other host| D[clientId guidance]
  B -->|anything else| E[original message]
  F[tests in oauth.rs] --> B

Loading

Start at registration_error in src/mcp/oauth.rs. It's the only file changed (+121/−1).

Regressions

None found. Non-403 failures are asserted to keep the exact old message.

One thing to know: the 403 check matches the text HTTP 403 Forbidden: that rmcp 2.2 puts in RegistrationFailed. If rmcp changes that format, the guidance silently stops showing and the old message returns. sdk_registration_forbidden_response_gets_actionable_guidance uses the real SDK against a local server, so the tests would catch it on upgrade.

Migrations

None.

Before merging

• Optional: open the TUI MCP dialog and check how the multi-line message wraps

[Blankeos]

Follow-up on whether this blocks people using crabcode with the Figma MCP.

For the remote server (mcp.figma.com), yes. Figma only lets clients in its MCP catalog connect, and its docs say new clients go through a waitlist (known issues). Registration returns a 403 before any browser step, and nothing in crabcode can get past that. The real fix is crabcode getting approved by Figma. That's a request to Figma, not a code change, and this PR only makes the failure explain itself.

Workaround today: the Figma desktop MCP server.

• Needs the Figma desktop app and a Dev or Full seat on a paid plan (setup).
• It has no browser OAuth and doesn't support writing to the canvas or sending UI to Figma.
• Config: mcp.figma with url: http://127.0.0.1:3845/mcp and oauth: false. I didn't run this end to end because it needs the desktop app with a Dev seat.

Follow-ups, none needed for this PR:

• Apply to Figma's MCP client waitlist for crabcode.
• Add the desktop-server config to the MCP docs or README, so people find it before hitting the error.

I'm not suggesting spoofing another client's name to get past the allowlist.