docs: add authentication guide and scope MCP guide to AIQ 2.1

[AjayThorve]

Summary

Two doc-only commits in the customization + deployment areas:

1. New docs/source/deployment/authentication.md — operator-facing guide covering OAuth/OIDC sign-in, backend JWT validation, AIQ user-token use in tools, AIQ-token pass-through to MCP integrations, headless API caller pattern, and troubleshooting.
2. Rewrite docs/source/customization/mcp-tools.md — scoped tightly to what AIQ 2.1 actually supports end-to-end.

Both docs are wired into the deployment and top-level indexes.

What the MCP guide now covers

Supported patterns (full walkthroughs):

• mcp_client for unauthenticated MCP servers
• mcp_service_account (incl. dual-auth) for backend-credential MCP
• AIQ-user-identity tools using aiq_agent.auth.get_auth_token()
• nat mcp serve / nat fastmcp server run for publishing AIQ as MCP

Deferred to AIQ 2.2 / 2.3 (short, honest planning notes):

• Per-user MCP OAuth driven by the AIQ UI. NAT 1.6 ships the protocol-level building blocks (mcp_oauth2, per_user_mcp_client) but AIQ 2.1 lacks the UI controls, the per-MCP auth-status surface on /v1/data_sources, and the async-job worker-side per-user MCP token resolution required to deliver this end-to-end.
• A first-party AIQ-token pass-through MCP auth provider. Today this requires implementing a custom NAT auth provider in your deployment package.

Cuts vs. the previous draft

• The three "Options 1/2/3" pass-through recipes collapse to a single Forwarding AIQ User Identity from a Tool section with the working internal_search example.
• The long native per-user OAuth walkthrough (Jira example, redirect URI setup) is replaced by a short note pointing at the NAT MCP auth reference.
• The "Does AIQ Need Separate UI Login..." combinatorial table.
• A custom-provider Python skeleton for aiq_user_token_passthrough (the doc no longer recommends a flow AIQ does not ship out of the box).

Net for mcp-tools.md: 395 lines, down from 622 in the prior draft.

Test plan

• Docs build cleanly (sphinx)
• Doc-tree TOC includes the new authentication.md
• All cross-references between mcp-tools.md and authentication.md resolve

Notes

• Doc-only PR; no code changes.
• Markdown-link-checker may flag external sites that 403 the bot UA (FastAPI, Dask, Next.js, Postgres, LangGraph) — these were pre-existing in deployment/index.md, not introduced here.
• Follow-ups for AIQ 2.2 / 2.3 (per-user MCP OAuth UI, async-job auth refresh) are tracked separately under the auth/MCP umbrellas.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This doc-only PR adds a new authentication.md operator guide and rewrites mcp-tools.md to accurately reflect what AIQ 2.1 supports end-to-end. Both files are correctly wired into the Sphinx toctrees. The content is well-structured, cross-references between the two guides resolve correctly, and the decision to defer per-user MCP OAuth to 2.2/2.3 is clearly communicated.

Confidence Score: 5/5

Safe to merge; all findings are P2 and doc-only.

No P0 or P1 findings. The single P2 comment addresses reversed error-handling order in a TypeScript code example that operators may copy. The broader content is accurate and clearly scoped.

docs/source/deployment/authentication.md — the refreshMySSOToken example snippet has a minor error-handling order issue.

Important Files Changed

Filename	Overview
docs/source/deployment/authentication.md	New operator-facing auth guide covering OAuth/OIDC UI setup, JWT backend validation, data-source gating, and headless API callers. The refreshMySSOToken code example calls .json() before checking response.ok, breaking error handling for non-JSON error responses.
docs/source/customization/mcp-tools.md	Substantial rewrite scoping the guide to AIQ 2.1-supported patterns; adds service-account auth, user-identity forwarding, per-user OAuth planning notes, and troubleshooting sections.
docs/source/deployment/index.md	Adds a bullet entry linking to the new authentication.md; change is minimal and correct.
docs/source/index.md	Wires authentication.md into the top-level Sphinx toctree in the correct position within the Deployment section.

Sequence Diagram

sequenceDiagram
    participant User
    participant UI as AIQ UI (NextAuth)
    participant Backend as AIQ Backend (AuthMiddleware)
    participant Tool as Custom AIQ Tool
    participant Downstream as Downstream API / MCP Server

    User->>UI: Sign in (OAuth/OIDC)
    UI->>UI: Store session, set idToken cookie
    User->>Backend: Request (Bearer token or idToken cookie)
    Backend->>Backend: JWTValidator validates token
    Backend->>Tool: Execute tool (token in request context)
    Tool->>Tool: get_auth_token()
    Tool->>Downstream: HTTP call with Authorization: Bearer token
    Downstream-->>Tool: Response
    Tool-->>Backend: Tool result
    Backend-->>User: API response

Loading

_{Reviews (2): Last reviewed commit: "docs: address greptile review on PR 212" | Re-trigger Greptile}

[AjayThorve]

@greptileai

[cdgamarose-nv]

LGTM