[adityamishra-hydradb]

Document the complete MCP ingest and update flows

This change updates the public MCP reference for ENG-3328, ENG-3327, ENG-3333, ENG-3335, ENG-3334, and ENG-3339.

Why — the public reference omits shipped MCP behavior

The MCP page only documents single-item text and turns ingestion. It does not explain batch ingestion, structured app knowledge, complete document metadata, access-list replacement, or metadata edits. It also does not explain the new failure behavior for query and list responses.

What — complete tool contracts and runnable examples

The page now documents batch items, structured app_knowledge, extraction instructions, additional metadata, caller-supplied graphs, explicit relations, evidence fields, ACL semantics, ingest outcomes, and hydradb_update. It also explains query request IDs, list failure behavior, metadata limits, read-side ACL filtering, collection scope, and retry behavior.

How — agents follow one documented flow

---
config:
  flowchart:
    wrappingWidth: 1000
---
flowchart LR
  A["Ingest one item<br/>or a batch"] --> B["Check per-item<br/>acceptance"]
  B --> C["Wait for accepted items<br/>with hydradb_status"]
  C --> D["Resolve an item ID<br/>with query, list, or inspect"]
  D --> E["Merge metadata<br/>or replace its ACL"]
  E --> F["Retry the same edit<br/>until fully converged"]

Loading

1. Ingest: Send one input mode and preserve document metadata or access rules.
2. Check: Distinguish accepted, rejected, and partially accepted items.
3. Resolve: Wait for accepted items and copy the exact item ID and collection.
4. Update: Merge selected metadata keys or replace the complete access list.
5. Converge: Retry identical edits after partial persistence or index-sync errors.

In one line: The public MCP reference now matches the shipped ingest, ACL, failure, and metadata-update contracts.

Testing

Final head: e03c95a6ef2242624218bcbcfefe7e2f3d20af01

Documentation validation

npx -y pnpm@9 install --frozen-lockfile
./node_modules/.bin/mintlify validate --no-telemetry
./node_modules/.bin/mintlify broken-links --no-telemetry
npm run hygiene:strict
/var/tmp/mintlify-docs-py/bin/python .github/verify_v2_public_contract.py
/var/tmp/mintlify-docs-py/bin/python -m unittest discover -s .github -p 'test_v2_schema_types.py'
/var/tmp/mintlify-docs-py/bin/python -m unittest discover -s scripts -p 'test_sync*.py'

All commands passed. Mintlify found no broken links, and strict hygiene found no issue.

Browser validation

./node_modules/.bin/mintlify dev --no-open --no-telemetry
curl -sS -o /dev/null -w 'preview HTTP %{http_code}\n' http://localhost:3000/plugins/mcp

The changed MCP page loaded on desktop and at 390 × 844. All examples were aligned and readable. Browser wheel checks moved each narrow code block horizontally, which verified contained overflow.

Local HydraDB example validation

HYDRADB_BASE_URL=http://127.0.0.1:19001 \
HYDRADB_DATABASE=docs-mcp-test-3328 \
HYDRADB_COLLECTION=docs-mcp-fixtures \
HYDRADB_TIMEOUT_SECONDS=40 \
HYDRADB_MAX_RETRIES=0 \
node *[docs-mcp-e2e.mjs]*

node *[docs-mcp-verify.mjs]*
node *[docs-mcp-acl.mjs]*

Results:

• Batch memory: two accepted, zero rejected, and both reached completed indexing.
• Structured app knowledge: one ticket accepted and indexed. Alice could read it; Bob could not.
• Metadata update: database and additional metadata merged without removing existing values.
• ACL replacement: Bob could read before replacement and was denied afterward. Alice and group:linear:platform could read after replacement.
• The harness substituted only the disposable collection name. The documented JSON values matched the tested values.
• No staging or production API was called.
• Cleanup removed the disposable database, stack, containers, volumes, queues, and task worktree.

A first update attempt exposed an invalid example principal, group:platform. The final page uses the valid group:linear:platform form, and the corrected request passed.

A memory-list probe on the independent ingest branch reproduced the camelCase adapter issue fixed by ENG-3328 in PR 115. The changed examples do not call hydradb_list; PR 115 has its own final-head A/B proof for that path. The fixed merge order remains PR 115 before PR 116.

Automated review

• Independent review: 2/10, Low risk, safe to ship.
• Greptile: 5/5 on final head e03c95a6ef2242624218bcbcfefe7e2f3d20af01 with no new findings.
• OpenHack: 5/5 on final head with zero reportable findings.
• Earlier Greptile findings were fixed, replied to, and resolved.
• No unresolved Greptile, Devin, or OpenHack review threads remain.

Risk Assessment

Score: 2/10 — Low.

Verdict: Safe to ship. No reviewed documentation blocker remains.

Concerns:

1. Publication must follow the documented code-PR merge order.
2. Access lists scope permission-aware reads; they do not authenticate callers. The page now states this boundary explicitly.

Rollout

Publish this documentation after the linked MCP and backend changes. Do not publish it ahead of the code contracts it describes.

---

Session Details

• Session: View Session
• Requested by: Aditya Mishra (aditya.mishra@hydradb.com)
• Address comments on this PR. Add (aside) to your comment to have me ignore it.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Nov 11, 2026, 12:46 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

✅ Mintlify Hygiene

No issues found.

[openhack-agent]

OpenHack Summary

Security review of docs(mcp): cover ingest batches and metadata updates. 1 changed file; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• plugins/mcp.mdx (modified)

Last reviewed commit: 49280fc · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The documentation appears safe to merge, provided publication follows the linked code changes as planned.

Summary

The PR expands the MCP reference to cover batch ingest, structured app records, access lists, and metadata edits.

• The MCP reference explains how callers search and give feedback.
• The ingest guide shows how to send batches and check their outcomes.
• Callers can follow the documented steps to merge metadata or replace access.
• The MCP reference explains how callers read and manage stored sources.
• The MCP reference explains database access and management tools.
• The MCP reference maps connector, graph, and older tool names.

The earlier comments about batch outcomes, metadata limits, and embedding flags are addressed in the current page. No new actionable issues were found.

_{Reviews (11) · Last reviewed commit: "docs(mcp): mark update tool and list err..." · Reviewed by Greptile}

[vorflux]

@greptile-apps please re-review final head e03c95a6ef2242624218bcbcfefe7e2f3d20af01. The two prior findings are fixed and resolved.

@openhack-agent please review final head e03c95a6ef2242624218bcbcfefe7e2f3d20af01.

[adityamishra-hydradb]

@greptileai review

[adityamishra-hydradb]

/devin review

[devin-ai-integration]

Starting Devin Review.

[devin-ai-integration]

🔍 Devin Review: 1 flag

Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[adityamishra-hydradb]

@greptileai review

[adityamishra-hydradb]

/devin review

[devin-ai-integration]

Starting Devin Review.

[capy-ai]

Fresh independent review of head 197bc1c. Current-head Greptile 5/5 and green checks do not clear the publication dependency gate. I ran MCP main a491ead95a27f3acb9dcb7cf7c49928c9a59d77d with its actual pinned SDK 2.1.8 and real MCP serialization, replacing only HTTP with synthetic offline fixtures. Typecheck and the existing unit suite passed (656 passed, 1 skipped), but the documented update tool is unavailable and ordinary list failures are still masked. Please keep this PR unmerged until the dependencies below are merged and released, then verify the same calls against that released implementation; alternatively explicitly scope these sections as unreleased. No author branch was modified and no production service was called.

[capy-ai]

[P1] Publication depends on the update tool actually shipping. MCP main a491ead95a27f3acb9dcb7cf7c49928c9a59d77d does not register hydradb_update: tools/list omits it, and calling the documented id/collection/additional_metadata flow returns isError:true with MCP error -32602: Tool hydradb_update not found. hydra-db/hydradb-mcp#120 is still open/unmerged. Keep this reference gated until #120 is merged and released, or clearly mark the tool unavailable in the current release; publishing this as an available tool now gives readers an unusable edit flow.

[adityamishra-hydradb]

Not a doc defect. It is a merge-order dependency, which is correct as you describe it. On main, hydradb_update does not exist. hydradb-mcp PR 120 adds it (head e3ec92b41, up to date with main). That head registers the tool with the documented id / collection / additional_metadata flow. The test hydradb_update merges both metadata maps and replaces a named ACL in tests/server-tools.test.ts covers it. Locally: 672 pass, 0 fail, 1 skip.

This page describes the behavior after PR 120 ships. It is meant to merge only after PR 120 is merged and released. The human merge order controls that, not the doc text. No change to the doc in bac49df (that commit only merges main).

[adityamishra-hydradb]

Fixed in 49280fc. The hydradb_update section now has a note: the tool needs a hydradb-mcp release later than 1.7.0, and 1.7.0 and earlier do not have it. The tool itself ships in hydradb-mcp PR 120.

[capy-ai]

[P1] This error guarantee is not true for the current ordinary list path. Through the real SDK and MCP server on main a491ead95a27f3acb9dcb7cf7c49928c9a59d77d, call hydradb_list({kind:'knowledge'}) and return HTTP 200 with either {success:true,data:{}}, {success:false,data:{sources:[]},error:{message:'store unavailable'}}, or <html>Sign in</html> from the synthetic HTTP fixture. Every case returns No sources found. with items:[] and no isError flag. A valid user_memories row also disappears on the memory path. hydra-db/hydradb-mcp#115 remains open. Hold this promise until that fix is merged/released and these ordinary, unfiltered cases independently pass; filtered-list checks alone do not establish this guarantee.

[adityamishra-hydradb]

Not a doc defect. It is the same dependency: the cases you ran come from main, which does not have hydradb-mcp PR 115. At PR 115 head e7cdd597f (up to date with main), the unfiltered list path rejects each of those bodies:

• tests/hydra-wrapper.test.ts (around line 731) checks HTML <html><title>Login required</title></html>, {success:true,data:{}}, {success:false,data:{sources:[]}}, and the nested success:false variants. It expects INVALID_LIST_RESPONSE and no No sources found.
• tests/server-tools.test.ts (around lines 1707-1720) checks that a valid user_memories row stays on the memory path.

Locally on PR 115: 668 pass, 0 fail, 1 skip. Type check and lint are clean. This page should merge only after PR 115 is merged and released, as stated above. No change to the doc text.

[adityamishra-hydradb]

Fixed in 49280fc. The list error promise now says it needs a hydradb-mcp release later than 1.7.0, and that 1.7.0 and earlier can show these failures as an empty list. The behavior ships in hydradb-mcp PR 115.

[adityamishra-hydradb]

@greptileai review

[adityamishra-hydradb]

/devin review

[devin-ai-integration]

Starting Devin Review.

[adityamishra-hydradb]

@capy-ai please re-review: the findings from your last review are fixed in 49280fc (see the replies).

[adityamishra-hydradb]

@greptileai review

[adityamishra-hydradb]

/devin review

[devin-ai-integration]

Starting Devin Review.

[SohamRatnaparkhi]

Rollout review: MCP #115 has merged. MCP #120 needs a merge update after #115; the combined local suite passes 684 tests with 1 skipped. Keep this documentation unpublished until #120 merges and the MCP release contains BOTH changes. A merge to main by itself is not a verified package/server release.

[SohamRatnaparkhi]

MCP #120 is superseded by hydra-db/hydradb-mcp#127 to retain the verified combined implementation with DCO sign-off. Publication gate now follows #115 + #127 and the resulting MCP release.

[SohamRatnaparkhi]

Release prerequisite is prepared in MCP #127: version 1.8.0 includes #115 and the former #120 update tool. Version 1.7.0 already exists on npm, so #127 now bumps the version to prevent the publish workflow silently skipping the new tools. Keep this doc held until 1.8.0 is actually published/released.

[SohamRatnaparkhi]

Publication hold per Soham: do not merge this docs PR automatically. He does not want all available MCP tools listed in public docs. This diff adds an extensive Available Tools catalog, including database/schema, connector lifecycle/resource, graph, and deprecated-name sections; that scope needs to be reduced before publication. Summarize the proposed documentation changes and wait for his explicit approval of this specific docs PR, even after the MCP release.