docs: document API-to-product vocabulary mapping (gateway/server → MCP server/virtual server) - #6770
docs: document API-to-product vocabulary mapping (gateway/server → MCP server/virtual server)#6770marekdano wants to merge 1 commit into
Conversation
…P server/virtual server) Signed-off-by: Marek Dano <mk.dano@gmail.com>
There was a problem hiding this comment.
Looks good! Non-blocking considerations LLM review surfaced:
Consideration: the doc says contextforge-web-ui#85 tracks moving the React UI onto the /v1 paths and describes the UI as currently calling the legacy paths directly. contextforge-web-ui PR #98 (closes #85) is already open and under review, migrating all frontend calls to /v1/mcp-servers and /v1/virtual-servers. If #98 merges before this doc does, the statement is immediately stale. The fix is to replace the forward-looking sentence with something that stays accurate regardless of merge order, for example: note that #85 tracked this migration, and that PR #98 completed it.
Minor issue: the base branch for this PR is chore/mcp-sdk-v2, not main. If this doc merges into that integration branch and chore/mcp-sdk-v2 later merges to main, the page will arrive correctly. But if the branch is abandoned or rebased before merge, the doc needs to be retargeted. Not a blocker, just worth confirming the intended merge path.
2 participants
Closes #6543
Summary
The React UI uses product terms — MCP server, virtual server, A2A agent — while the API still uses its original vocabulary (
gateway,server) in routes, models, permission strings, and audit records. That gap was undocumented, so readers couldn't tell whether a mismatch was a bug or expected. This adds the mapping.docs/docs/overview/terminology.md: a mapping table (product term → routes / model & table / RBAC permissions / auditresource_type), a callout that "server" is ambiguous and must always be qualified, guidance to lead with the/v1/mcp-serversand/v1/virtual-serverspaths over the deprecated unversioned aliases (sunsetSat, 26 Sep 2026), and a pointer to_RESOURCE_LABELSinmcpgateway/routers/log_search.pyas the one place that already renders product terms correctly.a2a_servicelogs throughStructuredLogEntryrather thanAuditTrail.docs/docs/overview/.pages.Docs only, no code changes.
Test plan
npx markdownlint-cli2passes on the new filemkdocs buildsucceeds; new page renders at/overview/terminology/and appears in nav. (--strictfails only on 16 pre-existing broken anchors elsewhere in the docs tree, unrelated to this change.)