Update references to py-key-value in the docs

[strawgate]

Enhancement

While we reference that py-key-value supports many backend stores, users should review the py-key-value documentation to understand the maturity and limitations of a particular backend store before using it as unstable/preview stores may not be suitable for production use

[marvin-context-protocol]

Claude finished @strawgate's task —— View job

---

Investigation Complete

Issue Type: Documentation Enhancement

---

Recommendation

Add a cautionary note to the docs/servers/storage-backends.mdx file after line 144 where alternative py-key-value-aio backends are listed. The note should direct users to review the py-key-value-aio documentation to understand backend maturity and limitations before using them in production.

Suggested addition (after line 144):

<Warning>
Before using these backends in production, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have specific constraints that make them unsuitable for production use.
</Warning>

This warning should be placed immediately after line 144 (For configuration details on these backends, consult the [py-key-value-aio documentation](https://github.com/strawgate/py-key-value).) and before line 146 (## Use Cases in FastMCP).

---

Findings

The documentation currently references py-key-value-aio in four locations:

1. docs/servers/storage-backends.mdx (primary documentation)

   • Line 16: Introduction mentioning the library
   • Line 82: Note about optional Redis dependency
   • Lines 133-144: Section listing alternative backends
   • Line 144: Link to py-key-value-aio documentation

2. docs/clients/auth/oauth.mdx

   • Line 128: Brief mention in OAuth token storage context

3. docs/changelog.mdx and docs/updates.mdx

   • Historical release notes describing the feature

Primary location for enhancement: docs/servers/storage-backends.mdx lines 133-144 is where users learn about alternative backends like DynamoDB, MongoDB, Elasticsearch, Memcached, RocksDB, and Valkey. This is the most appropriate place to add a maturity/limitations warning.

Current text (lines 133-144):

### Other Backends from py-key-value-aio

The py-key-value-aio library includes additional implementations for various storage systems:

- **DynamoDB** - AWS distributed database
- **MongoDB** - NoSQL document store
- **Elasticsearch** - Distributed search and analytics
- **Memcached** - Distributed memory caching
- **RocksDB** - Embedded high-performance key-value store
- **Valkey** - Redis-compatible server

For configuration details on these backends, consult the [py-key-value-aio documentation](https://github.com/strawgate/py-key-value).

The current documentation:

• ✅ Links to py-key-value-aio documentation (line 144)
• ❌ Does not warn users about checking backend maturity
• ❌ Does not mention that some backends may be preview/unstable

Detailed Action Plan

1. Edit docs/servers/storage-backends.mdx

   • Add a <Warning> callout after line 144
   • Keep it concise but actionable
   • Link to the py-key-value documentation for details
   • Position it before the "Use Cases in FastMCP" section

2. Consider secondary enhancement (optional)

   • Could add a brief note in docs/clients/auth/oauth.mdx line 128 area
   • But primary fix in storage-backends.mdx is most important

3. Verification

   • Check that docs.json includes the modified file (it should, since it's already referenced)
   • Run pre-commit checks: uv run pre-commit run --all-files
   • Verify documentation renders correctly locally: just docs

Related Issues and Pull Requests

Repository	Item	Relevance
jlowin/fastmcp	#2216: Dead link for py key value	Previous documentation fix for py-key-value links (merged in PR #2217)
jlowin/fastmcp	#2072: Secret storage	Original issue tracking need for secure storage, led to py-key-value integration
jlowin/fastmcp	#1913: Add Storage to FastMCP	PR that integrated py-key-value-aio into FastMCP (v2.13.0)
jlowin/fastmcp	#2137: Add storage backend documentation	PR that created the storage-backends.mdx file being modified

Related Files

Repository	File	Relevance	Key Sections
jlowin/fastmcp	docs/servers/storage-backends.mdx	Primary file requiring modification	Lines 133-144 (Other Backends section)
jlowin/fastmcp	docs/clients/auth/oauth.mdx	Secondary location mentioning py-key-value	Line 128 (Token Storage section)
jlowin/fastmcp	pyproject.toml	Shows py-key-value-aio dependency	Line 18 (version constraint)

Related Webpages

Name	URL	Relevance
py-key-value GitHub Repository	https://github.com/strawgate/py-key-value	Official documentation for backend maturity and limitations
FastMCP Storage Backends Docs	https://gofastmcp.com/servers/storage-backends	Live documentation page requiring update

---

[strawgate]

/marvin please make sure we add a note to any references to the library and please make the pr

[marvin-context-protocol]

Claude finished @strawgate's task —— View job • claude/issue-2310-20251029-2141 • Create PR ➔

---

Adding py-key-value maturity warnings to documentation

Tasks

• Read current documentation files
• Add warning to docs/servers/storage-backends.mdx after line 144
• Add note to docs/clients/auth/oauth.mdx after line 128
• Run pre-commit checks
• Commit and push changes
• Provide PR creation link

Changes Made

Added warning notes to two documentation files where py-key-value backends are referenced:

docs/servers/storage-backends.mdx (after line 144):

• Added <Warning> callout directing users to review backend maturity before production use
• Positioned after the list of alternative backends (DynamoDB, MongoDB, Elasticsearch, etc.)

docs/clients/auth/oauth.mdx (after line 128):

• Added <Note> callout with similar guidance for token storage backend selection
• Positioned after mentioning AsyncKeyValue-compatible backends

Both notes link to the py-key-value documentation and emphasize checking for preview/unstable backends.

Summary

All warning notes have been added to references of py-key-value backends in the documentation. Pre-commit checks passed successfully. Changes have been committed and pushed to the branch.

---

|