docs: MCP user-guide notebook (search, upsert, ADK agent, JWT auth)

[nkanu17]

Summary

Adds a hands-on MCP user-guide notebook (docs/user_guide/15_mcp.ipynb) that walks the full RedisVL MCP loop end to end, now including a JWT authentication section aligned with the optional auth feature shipped in #628.

The branch has been rebased onto main (v0.21.0) so it sits cleanly on top of the JWT auth work.

What's in the notebook

1. Create and load an index — ordinary RedisVL flow (schema, local HFTextVectorizer embeddings, load).
2. Write the MCP config — bind one logical server to one existing index; default_embed_text_field so clients only ever send text.
3. Start the server over Streamable HTTP with a real MCP-handshake readiness probe.
4. Call the tools — search-records and upsert-records via a plain fastmcp client.
5. Google ADK agent — point an LlmAgent at the same endpoint with McpToolset.
6. Secure the server with JWT authentication (new) — start a second, authenticated server using a server.auth block, then demonstrate coarse read/write gating.

New auth section (Section 6)

• Frames RedisVL MCP as an OAuth resource server: validates IdP-issued JWTs (signature, issuer, audience, expiry); stdio is never authenticated.
• Mints a throwaway RSAKeyPair and validates against its static public_key, so the demo needs no external IdP.
• Demonstrates: no token → 401, read-only token → search OK / upsert FORBIDDEN, read+write token → upsert OK.
• Updates the Section 3 warning, the Cleanup cell (tears down the auth server + config), and the Recap; links to the new Authenticate RedisVL MCP how-to guide.

Downstream changes

• docs/user_guide/how_to_guides/index.md — adds the notebook to the CLI Operations card, quick-reference table, and toctree (alongside the auth how-to from feat(mcp): optional JWT authentication for HTTP transports #628; rebase conflict resolved to keep both).

Verification / Testing

The notebook was executed end to end against a live Redis (Search enabled), running every cell except the %pip install cells — all cells passed, 0 errors:

Section	Result
Connect to Redis	✅
1. Create + load index	✅ 4 records loaded
2. Write + validate MCP config	✅
3. Start server	✅ both tools exposed via MCP handshake
4. Client search-records	✅ vector, 3 results
4. Client upsert-records	✅ keys_upserted=1, retrievable via follow-up search
5. ADK agent (search)	✅ grounded answer, correct search-records tool call (real OpenAI call)
5. ADK agent (save)	✅ correct upsert-records tool call
6. JWT auth	✅ no token → 401, read → search OK / upsert FORBIDDEN, read+write → upsert OK
Cleanup	✅ both servers stopped, index dropped, config files removed

Live cells require Redis with Search and the redisvl[mcp,sentence-transformers] extras; the ADK section additionally needs google-adk, litellm, and OPENAI_API_KEY. Auth API usage (RSAKeyPair, BearerAuth, create_token(..., scopes=...), scope gating) mirrors the in-repo integration tests in tests/integration/test_mcp/test_transport_auth.py.

Kept as a draft.

---

Note

Low Risk
Documentation and notebook examples only; no application or MCP server code changes.

Overview
Adds docs/user_guide/15_mcp.ipynb, an end-to-end user guide for serving a RedisVL index via rvl mcp: create/load an index, write and validate YAML config, start Streamable HTTP (terminal or notebook subprocess with MCP handshake readiness), call search-records / upsert-records with fastmcp, wire a Google ADK LlmAgent via McpToolset, and run a Section 6 JWT demo (second server on port 8001, read/write scope gating) aligned with the auth how-to. Includes security warnings, cleanup for both servers, and links to mcp.md / mcp_authentication.md.

Updates docs/user_guide/how_to_guides/index.md to surface the notebook in the CLI Operations card, quick-reference table, and hidden toctree.

^{Reviewed by Cursor Bugbot for commit 8c703e4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[Copilot]

Pull request overview

Adds a new user guide notebook documenting how to serve an existing RedisVL index over MCP (including client usage and a Google ADK agent example), and wires it into the docs navigation. Also updates the lockfile to reflect the project version bump.

Changes:

• Add docs/user_guide/15_mcp.ipynb walkthrough for serving an index over MCP and using search-records/upsert-records (plus ADK integration).
• Update docs/user_guide/how_to_guides/index.md to link the new MCP notebook in cards, quick-reference table, and toctree.
• Update uv.lock to reflect redisvl version 0.20.0.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.

File	Description
uv.lock	Updates the editable redisvl package entry to version 0.20.0.
docs/user_guide/how_to_guides/index.md	Adds navigation entries pointing to the new MCP notebook.
docs/user_guide/15_mcp.ipynb	Introduces a hands-on MCP notebook (index creation, config, server/client usage, ADK agent example, cleanup).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0738063. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[vishal-bala]

We have a similar notebook in applied-ai-resources for working with ADK and a RedisVL MCP server - would it be beneficial to add the JWT auth functionality to that one, or is there a push to have a separate notebook for the topic as part of the user guide as well?

https://github.com/redis-developer/redis-ai-resources/blob/main/python-recipes/MCP/00_google_adk_redisvl_mcp_agent.ipynb