docs(mcp): comprehensive MCP server documentation

[joshrotenberg]

Summary

Write comprehensive documentation for the MCP server covering setup, configuration, safety, and the full tool catalog. Good docs are critical for adoption -- operators need to understand the safety model, and agents need to discover capabilities.

Deliverables

Getting started guide

• Installation (binary, cargo install, Docker)
• First run with stdio transport (Claude Desktop, Cursor, VS Code)
• First run with HTTP transport
• Profile setup for Cloud, Enterprise, and direct database connections
• Verifying connectivity with profile_validate

Client configuration guides

• Claude Desktop: claude_desktop_config.json setup with examples
• Cursor: MCP server configuration
• VS Code (Continue, Cline): Integration setup
• Custom clients: HTTP/SSE transport with optional OAuth

Safety and policy guide

• Default safety posture (read-only by default)
• The three policy tiers: read-only, read-write, full
• redisctl-mcp.toml configuration reference (feat(mcp): granular allow/deny policy configuration (redisctl-mcp.toml) #766)
• Per-toolset policies
• Allow/deny lists with examples
• Per-profile policies
• Raw API tool gating (feat(mcp): add raw API passthrough tools #768)
• Best practices for production deployments

Tool catalog / reference

• Auto-generated or hand-curated list of all tools
• Grouped by toolset (cloud, enterprise, database, profile)
• Each tool: name, description, parameters, safety annotation, example
• Consider generating from tool metadata at build time

Audit logging guide (#767)

• Enabling audit logging
• Log format reference
• Integration with log aggregation (ELK, Datadog, etc.)
• Interpreting denied operation logs

Architecture overview

• Feature flags and toolset composition
• Profile resolution and credential management
• Transport modes (stdio vs HTTP/SSE)
• OAuth configuration for multi-tenant deployments
• Rate limiting and concurrency control

Troubleshooting

• Common errors and remediation
• Credential resolution failures
• Policy misconfiguration
• Transport issues

Format considerations

• Primary format: markdown files in docs/mcp/ directory
• Consider mdBook for a structured documentation site
• Tool catalog could be auto-generated from source annotations
• Include in repository (version-controlled with the code)

Acceptance criteria

• Getting started guide written and tested
• At least two client configuration guides (Claude Desktop + one other)
• Safety and policy guide complete
• Tool catalog with all 199+ tools documented
• Audit logging guide
• Architecture overview

Context

Part of #681 (MCP epic). Documentation should be written alongside feature work, not after. Each issue in this epic should include doc updates as part of its acceptance criteria.

[joshrotenberg]

Status Update

Significant progress on this issue. Here's what's now covered:

Done

• Getting started guide (installation, credentials, starting the server, IDE config for 6 clients)
• Client configuration guides -- Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Continue), Zed
• Safety and policy guide -- read-only default, three tiers, policy file reference, per-toolset overrides, allow/deny lists
• Tool catalog -- 309 tools documented with sub-module groupings, representative tools per module, summary table
• Configuration page -- full CLI reference, --tools syntax, safety tiers, presets, decision table
• Cloud and Enterprise quickstart guides
• Workflows page with real-world examples

Remaining

• Audit logging guide (how to enable, log format, integration with log aggregation)
• Architecture overview (feature flags, transport modes, OAuth, rate limiting internals)
• Auto-generated tool reference (tracked in refactor(mcp): declarative tool definitions to reduce boilerplate #791 as part of declarative tool definitions)
• Troubleshooting expansion (currently basic)

The bulk of the operator-facing documentation is in place. The remaining items are nice-to-haves rather than blockers.

[joshrotenberg]

Update: the safety and policy configuration guide has been partially addressed in PR #804's branch (docs/mcp-safety-policy-guide), which added docs/docs/mcp/safety-policy-guide.md covering:

• Default safety posture (read-only by default)
• The three policy tiers: read-only, standard, full
• redisctl-mcp.toml configuration reference with examples
• Per-toolset policies, allow/deny lists
• Per-profile policies
• Raw API tool gating
• Production deployment best practices

Remaining deliverables from this issue:

• Getting started guide
• Client configuration guides (Claude Desktop, Cursor, VS Code)
• Tool catalog / reference
• Audit logging guide
• Architecture overview
• Troubleshooting