Redirect URL documentation fix — design

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Date: 2026-04-15 Area: agen-for-work/connectors/ Type: Documentation correction + tooling update

Problem

All 19 Agen for Work marketplace connector guides under agen-for-work/connectors/marketplace/ hardcode an incorrect OAuth Redirect URL:

https://api.frontegg.com/app-integrations/resources/integrations-callback/v1/dev-callback
https://api.us.frontegg.com/app-integrations/resources/integrations-callback/v1/dev-callback

The correct Redirect URL is a single, tenant-specific value built from the tenant's MCP Gateway URL (described in agen-for-work/settings/overview.md):

https://<MCP Gateway URL>/integration-callback

When a custom domain is configured, the pattern becomes:

https://<custom_domain>/integration-callback

Additionally:

• There is no shared reference page explaining how to construct this URL.
• Screenshots in the 19 guides show the wrong URL (typed into real provider UIs), so text fixes alone are insufficient — the screenshots must be re-captured.
• The create-integration-doc skill embeds the same wrong URLs in both its process instructions and its markdown template, so any future connector guide inherits the bug.

Goals

1. Introduce a single source of truth describing how to get the Redirect URL.
2. Replace hardcoded wrong URLs across all 19 marketplace guides with a placeholder that points users to the shared page.
3. Re-capture all screenshots that show the Redirect URL value inside provider UIs.
4. Update the create-integration-doc skill so it produces correct guides going forward.
5. Keep the change scoped to one PR, split into logical phased commits.

Non-goals

• No changes to agen-for-work/settings/overview.md content (only linking to it).
• No restructuring of connector categories or sidebar groups beyond adding one entry.
• No changes to CIAM or other product documentation — this is Agen for Work only.
• No audit or rework of OAuth scopes in existing guides.

Design

1. New shared page — agen-for-work/connectors/redirect-url.md

Purpose: single source of truth for how to construct the Redirect URL.

Structure:

• ## Get your Redirect URL — intro paragraph, explains the URL is needed when configuring OAuth applications in third-party services.
• ### URL format — the formula:
  https://<MCP Gateway URL>/integration-callback

• ### Find your MCP Gateway URL — short instruction: open Settings → Basic configuration, copy the MCP Gateway URL value. Link to ../settings/overview.md. One LightboxImage screenshot of the Settings page with the MCP Gateway URL field highlighted.
• ### Using a custom domain — if a custom domain is configured in Settings, use:
  https://<custom_domain>/integration-callback

  Link to the custom-domain section of settings/overview.md.
• ### Example — one realistic example using a placeholder tenant: https://your-tenant.mcp-gw.frontegg.com/integration-callback.

Formatting must satisfy scripts/check-content-style.mjs: first heading H2, subsequent H3+, sentence case, no emojis, → arrows.

2. Sidebar update — agen-for-work/sidebars.yaml

Add one entry inside the Connectors group, above the Marketplace subgroup:

- label: Redirect URL
  page: connectors/redirect-url.md

Exact placement preserves existing Marketplace ordering.

3. Marketplace guides — text changes (19 files)

Affected files (all under agen-for-work/connectors/marketplace/): asana, airtable, clickup, databricks, front, helpscout, hubspot, intercom, linkedin, monday, pagerduty, servicenow, shopify, surveymonkey, todoist, twitter, wordpress, zendesk, zoom.

For each file:

• In the step titled "Configure redirect URI" / "Add redirect URL" (wording varies per provider), replace the two hardcoded URLs and any accompanying sentence like "If the service allows only one redirect URI, use the first one" with:

  Enter your Frontegg Redirect URL:
  
  ```
  https://<your-mcp-gateway-url>/integration-callback
  ```

• In the ### Additional resources section at the bottom of the file, add:

  - [How to get your Redirect URL](../redirect-url.md)

No other text or step-numbering changes.

4. Screenshot re-capture (19 connectors)

For each connector, identify and regenerate every screenshot that visibly contains the Redirect URL value (typically in the provider's OAuth settings page after the URL has been pasted). Screenshots that only show the "Add redirect URL" button or an empty dialog are left untouched.

Rules (inherited from .claude/skills/create-integration-doc):

• Browser window fixed at 1920×1080.
• UI language English.
• Placeholder URL used when typing into provider UI: https://your-tenant.mcp-gw.frontegg.com/integration-callback. Fallback: if the provider validates the URL and rejects the placeholder, use the real MCP Gateway URL of the integrations@frontegg.com test tenant and blur the tenant-specific subdomain prefix.
• Existing rules for blur (secrets, emails, unrelated apps), highlight (red outline on key elements), and file naming ({integration-id}-N.png) still apply.
• Replace files in place at agen-for-work/connectors/marketplace/images/{integration-id}-N.png.

Execute one connector per sub-task; validate the page renders correctly before moving to the next.

5. create-integration-doc skill update

File: .claude/skills/create-integration-doc/SKILL.md (and referenced templates).

Changes:

• "OAuth Redirect URIs" default-settings section — replace the two hardcoded URLs with a single formula:
  Redirect URL format: https://<MCP Gateway URL>/integration-callback

  Add a sentence: "See agen-for-work/connectors/redirect-url.md for the canonical description — link to it from new guides."
• Markdown template in Step 3.1 — rewrite the "Configure redirect URIs" sample step to match the new pattern (placeholder URL in a code block, no "if the service allows only one…" sentence).
• Additional resources section of the template — add the bullet: - [How to get your Redirect URL](../redirect-url.md)
• Screenshot guidance — add a note: when typing the Redirect URL into a provider's UI for screenshots, prefer https://your-tenant.mcp-gw.frontegg.com/integration-callback; fall back to a real tenant URL only if the provider rejects the placeholder.
• Sidebar update instruction — unchanged (entry still goes under Marketplace); explicitly note that redirect-url.md is a shared page, not a per-connector page, and must not be duplicated.

6. Execution phases (one PR, atomic commits)

1. Create redirect-url.md + Settings screenshot + sidebar entry.
2. Bulk text update in 19 marketplace guides (no screenshot changes).
3. Update create-integration-doc skill (instructions + template).
4. Re-capture screenshots, one connector per commit (19 commits).
5. Run validation: npm run test and npm run check:content-style.

7. Validation

• npm run check:content-style — all 20 updated markdown files must pass.
• npm run test — Redocly lint must pass.
• Manual spot-check: open npm run dev preview, verify the new page renders, the sidebar entry appears, and at least 3 marketplace guides link correctly to redirect-url.md.

Open risks

• Provider URL validation — some OAuth providers refuse obviously fake redirect URIs. Mitigation documented in §4 (fallback to real tenant URL with blur).
• Custom domain behaviour — the spec assumes the Redirect URL path (/integration-callback) is identical under custom domain and default MCP Gateway URL. If backend behaviour differs, §1 needs a caveat. Confirm with backend team during phase 1 if uncertain.
• Screenshot drift — providers occasionally redesign OAuth settings pages; re-captures may require small step-text tweaks. Handle per-connector during phase 4.