Docs: Complete the HydraDB MCP production journey #214

Problem

The MCP integration page gets developers through basic configuration, but it does not yet provide a reliable production journey from installation to verified retrieval.

Several details also need to be reconciled with the current usecortex/hydradb-mcp implementation:

• The install examples pin @hydradb/mcp@0.0.1, while the current package is 1.0.0 and the MCP repository recommends @latest.
• The endpoint table documents GET /list/data and GET /fetch/content, while the current MCP client sends POST requests for both.
• The default HYDRA_DB_SUB_TENANT_ID=hydra-db-mcp behavior and its isolation implications are easy to miss.
• The seven available tools are listed, but developers do not get guidance on when to use each one, their important defaults, or how to validate the complete lifecycle.

This leaves a confusing gap between “the server starts” and “my agent is storing and recalling the right context.”

Proposed documentation journey

Update plugins/mcp.mdx to provide:

1. Current installation and runtime prerequisites.
2. Client configuration that explains tenant and sub-tenant isolation.
3. A tool decision table covering inputs, behavior, defaults, and side effects.
4. A complete verification flow: store → search → list → fetch → delete.
5. Clear guidance for infer, automatic upsert behavior, stable source_id values, recall mode, and graph context.
6. Troubleshooting that distinguishes startup/configuration errors, tools not appearing, and successful searches returning no memories.
7. Endpoint and terminology details verified against the current MCP source.

Acceptance criteria

• Installation examples use a current, maintainable package reference.
• All documented tools and HTTP methods match the current MCP implementation.
• Shared versus user-specific sub-tenant configuration is explained with concrete examples.
• A developer can verify the entire memory lifecycle from their MCP client.
• Important defaults and limitations are stated near the relevant workflow.
• Configuration and troubleshooting examples do not expose API keys.
• The page renders successfully with Mintlify.

Existing work / overlap

PR #180 makes a small cross-plugin cleanup that also touches plugins/mcp.mdx (terminology, default sub-tenant guidance, and the endpoint table). This issue is intentionally broader: it targets the complete MCP developer journey. The implementation should rebase on #180 if it merges first and retain compatible improvements without duplicating them.