Guided connector setup, setup status, and setup from the AI client - #834
Merged
Merged
Conversation
- REST engine: a 429 (or a 503 with Retry-After) gets at most one more attempt, after the API's Retry-After when it is 3 s or less, after ~1 s when there is none, and none when it asks for longer. Retrying 429s three times multiplied load on APIs that were already limiting us. - Errors for a missing variable or a never-authorized OAuth connector link to the connector's page; a host that does not resolve is reported as 'Host not found' instead of 'SSRF guard: cannot resolve'. - Error hints for Telegram (wrong bot token, unreachable chat) and Lexware (overdue cannot be combined with other statuses); Lexware list_vouchers marks voucherType and voucherStatus required; api-football healthPath typo fixed. - Onboarding drip: reminders depend on the workspace having no connector (a teammate's counts), not on the Skip flag of /welcome. A user who connected Claude/ChatGPT to an empty workspace gets the first nudge 2 h later, naming the client. New server-only event ai_client_connected.
…started - Pending authorizations move from an in-memory map to connector_oauth_attempts (state hashed, verifier and client credentials encrypted, 15 min, single use), so a restart or blue/green deploy between consent and callback no longer loses them. - The provider callback no longer exchanges the code: it checks the state and forwards code + state to /connectors/oauth/complete, which posts them to POST /api/mcp-oauth/complete. The code is exchanged only for the user who started the flow; anyone else gets 403 and the attempt is spent. Before, a consent link started on one person's connector could be completed by someone else, handing over that person's tokens. - Provider errors (access_denied, invalid_scope, invalid_client) are explained on the complete page, with a way back to the connector. - authorize accepts an internal returnTo; GET /api/connectors/oauth/redirect-uri returns the redirect URI from SERVER_URL, used by the connector form instead of guessing it from the browser's location.
- Setup status per connector (ready / needs_input / needs_authorization), computed from its variables and OAuth tokens. Connectors that are not ready are not listed on MCP (tools/list, per-server endpoints, shared /mcp); the shared endpoint names them under needsSetup with the link to finish them, and a call by name gets that link instead of a placeholder error. Checked against production: 213 of 1037 connectors are not ready, none of them had a successful call in 14 days. - Catalog: optional envVarMeta (label, kind, secret, help, example, pattern, link, advanced) with derived defaults for every adapter, curated for the 14 most installed; setupKind (none / credentials / oauth_browser); validator rule. - POST /api/adapters/:slug/verify tries the credentials against the adapter's probe on an in-memory connector before anything is saved. - /connectors/setup/<slug>: grouped fields with where to find them, check then install, 'Save and sign in' chaining the OAuth authorization with a return to the setup page, finish an existing connector, drafts instead of 'Skip for now'. The store installs through it; /welcome asks what to connect first. Setup funnel product events.
The shared /mcp keeps its eight tools. A virtual "AnythingMCP Setup" connector appears in anythingmcp_list_connectors for ADMIN and EDITOR members, with three tools reached through search/describe/run: setup_find_connectors, setup_install_connector and setup_get_status. - Install is catalog-only, accepts only non-secret settings, is limited to 10 installs per user per hour and respects the plan's connector limit. New connectors are attached to the servers the client was granted. - Secrets and OAuth sign-ins never pass through the chat: the tools return a one-time link (/s/<token>, 30 minutes, single use, only for the user it was made for) that opens the guided setup. - Cloud: after approving an AI client into a workspace with no connectors, a page explains how to add an app (in the chat or in a new tab) before handing back to the client.
… in the chat instructions, setup event kinds
…guided-setup # Conflicts: # packages/backend/src/adapters/adapters.service.spec.ts # packages/backend/src/adapters/adapters.service.ts
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
This was referenced Oct 3, 2026
…guided-setup # Conflicts: # packages/backend/src/adapters/de/lexware-office.json # packages/backend/src/audit/product-event.service.ts
…guided-setup # Conflicts: # packages/backend/prisma/schema.prisma # packages/backend/src/connectors/mcp-oauth-callback.controller.spec.ts # packages/backend/src/connectors/mcp-oauth-callback.controller.ts # packages/frontend/src/app/connectors/store/page.tsx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on #831 and #832 (both merged into this branch). Merge those first; this diff shrinks to its own two commits afterwards.
Why
Of the 428 sign-ups that came through the Claude directory in 48 hours, 146 connected Claude to a workspace with no connectors, and 213 connectors in the cloud were installed but could never work (178 missing a value, 35 never authorized). Their tools were still listed, so the model called them and got errors the user could not fix from the chat.
Setup status (dfa84f2)
ready,needs_input(a{{VAR}}still empty) orneeds_authorization(browser OAuth without a token)./mcp/<serverId>. The sharedanythingmcp_list_connectorsreports them underneedsSetupwith a link to finish.Guided setup (dfa84f2)
/connectors/setup/<slug>replaces the store's install dialog: fields grouped (address, credentials, settings, advanced collapsed), with help, examples and patterns from a new optionalenvVarMetain the adapter JSON (curated for 14 adapters, derived for the rest).POST /api/adapters/:slug/verify, no DB writes, 20/min per key)./welcomenow starts with "What should your AI client work with?".Setup from the AI client (df4d764)
/mcpkeeps its eight tools (no directory re-review). For ADMIN and EDITOR members a virtual "AnythingMCP Setup" connector appears inanythingmcp_list_connectors, withsetup_find_connectors,setup_install_connector,setup_get_status, run through the existing search/describe/run tools./s/<token>(30 min, single use, only for the user it was made for, SHA-256 stored) that opens the guided setup.Migrations
20261003110000_connector_setup_links(new table only).Tests