GPT Agent Data Connector Stability Fix

Date: 2026-05-12 Agent: Codex/CoreX Scope: GPT connector contract, Agent Data /kb/list, MCP schema, public OpenAPI

Summary

Implemented the connector-layer hardening requested for GPT <-> Agent Data:

• healthCheck is canonical REST/OpenAPI action mapped to GET /api/health.
• MCP does not expose a fake healthCheck tool; MCP exposes schema version/hash instead.
• listDocuments uses prefix, limit, and offset.
• REST ?path= on /kb/list is rejected with a clear 400 instead of silently returning the full KB.
• Default list limit is 50; max limit is 100.
• Large list responses are guarded with LIST_DOCUMENTS_RESPONSE_TOO_LARGE_USE_NARROWER_PREFIX.
• Connector logs now include wrapper name, upstream route, mapped query keys, status, response bytes, and schema version/hash where applicable.

Changed surfaces

Agent Data source on VPS:

• /opt/incomex/docker/agent-data-repo/agent_data/server.py
• /opt/incomex/docker/agent-data-repo/mcp_server/server.py
• /opt/incomex/docker/agent-data-repo/mcp_server/stdio_server.py
• /opt/incomex/docker/agent-data-repo/docs/api/openapi.yaml

Static GPT OpenAPI:

• /opt/incomex/docker/nginx/static/openapi.json
• /opt/incomex/docker/nuxt-repo/infra/nginx/static/openapi.json

Local workspace mirrors:

• automation/agent-data-openapi.json
• infra/nginx/static/openapi.json

Deploy

Build:

docker compose build agent-data -> PASS
new image sha256:9931ac1acb0458677c8deddce2922ecead6c2555cef6f3f9b77ecc869306d9f7

Restart:

docker compose up -d agent-data
only incomex-agent-data was recreated
incomex-qdrant stayed running and was only waited on as dependency

Health:

incomex-agent-data health_status=healthy

Public smoke evidence

OpenAPI:

GET /api/openapi.json -> 200
x-connector-schema-version=gpt-agent-data-2026-05-12.1
health operationId=healthCheck
listDocuments parameters=[prefix, limit, offset]

Health:

GET /api/health -> 200 healthy

List documents:

GET /api/kb/list?prefix=knowledge/dev/laws/dieu44-trien-khai/notes
-> 200 count=2 returned_count=2 limit=50 truncated=false

GET /api/kb/list?prefix=knowledge/dev/laws/dieu44-trien-khai/reviews&limit=10
-> 200 count=517 returned_count=10 next_offset=10 truncated=true

GET /api/kb/list?path=knowledge/dev/laws/dieu44-trien-khai/notes
-> 400 code=INVALID_LIST_DOCUMENTS_PARAMETER_USE_PREFIX

MCP schema:

initialize -> connectorSchemaVersion=gpt-agent-data-2026-05-12.1 connectorSchemaHash=5f13902e975a
tools/list -> list_documents input props=[path, limit, offset]
tools/call list_documents path=notes limit=10 -> 200 count=2 returned_count=2 truncated=false

3-round public/API-key stability smoke

Round 1:

healthCheck -> 200 healthy
searchKnowledge("OGV-2C write gate a40b217") -> 200 qdrant_hits=5 top=opus-gate-review-ogv-2c-case-closure-2026-05-07.md
getDocumentTruncated(opus gate review) -> 200 truncated=true
listDocuments(notes) -> 200 count=2 returned_count=2
listDocuments(reviews, limit=10) -> 200 count=517 returned_count=10 next_offset=10 truncated=true

Round 2:

healthCheck -> 200 healthy
searchKnowledge("OGV-2C write gate a40b217") -> 200 qdrant_hits=5 top=opus-gate-review-ogv-2c-case-closure-2026-05-07.md
getDocumentTruncated(opus gate review) -> 200 truncated=true
listDocuments(notes) -> 200 count=2 returned_count=2
listDocuments(reviews, limit=10) -> 200 count=517 returned_count=10 next_offset=10 truncated=true

Round 3:

healthCheck -> 200 healthy
searchKnowledge("OGV-2C write gate a40b217") -> 200 qdrant_hits=5 top=opus-gate-review-ogv-2c-case-closure-2026-05-07.md
getDocumentTruncated(opus gate review) -> 200 truncated=true
listDocuments(notes) -> 200 count=2 returned_count=2
listDocuments(reviews, limit=10) -> 200 count=517 returned_count=10 next_offset=10 truncated=true

Connector log evidence

connector_call wrapper=healthCheck upstream=/health mapped_query_keys=[] status=200 response_bytes=575 schema_version=gpt-agent-data-2026-05-12.1
connector_call wrapper=listDocuments upstream=/kb/list mapped_query_keys=prefix,limit,offset status=200 response_bytes=3628 prefix='knowledge/dev/laws/dieu44-trien-khai/reviews' limit=10 offset=0 returned_count=10 total_count=517
connector_call wrapper=listDocuments upstream=/kb/list mapped_query_keys=path status=400 failure_class=WRONG_QUERY_PARAMETER
connector_call wrapper=list_documents upstream=/mcp/tools/call mapped_query_keys=['limit', 'path'] status=200 response_bytes=814 schema_version=gpt-agent-data-2026-05-12.1 schema_hash=5f13902e975a

Remaining GPT-side action

The server and public OpenAPI are fixed. The GPT UI connector must refresh/reimport/reconnect its schema so it stops using any cached wrapper. After refresh, run the requested 3 GPT-side rounds:

healthCheck
searchKnowledge("OGV-2C write gate a40b217")
getDocumentTruncated("knowledge/dev/laws/dieu44-trien-khai/reviews/opus-gate-review-ogv-2c-case-closure-2026-05-07.md")
listDocuments(prefix="knowledge/dev/laws/dieu44-trien-khai/notes")
listDocuments(prefix="knowledge/dev/laws/dieu44-trien-khai/reviews", limit=10)

Status

connector_layer_fix=DEPLOYED public_api_smoke=PASS public_three_round_smoke=PASS codex_mcp_smoke=PASS gpt_side_smoke=NEEDS_GPT_CONNECTOR_SCHEMA_REFRESH no_pg_mutation=true no_qdrant_mutation=true no_ogv_2c_rollback=true