Artifact observability and support diagnostics

Gateway MCP developer schema responses should be easy to debug while preserving default-deny public visibility. Support packets should focus on hashes, versions, timestamps, and public-safe request metadata.

Client diagnostics to capture

When reporting an artifact issue, include:

• Gateway MCP tool name;
• public provider and operation identifiers shown in the response;
• artifactVersion, registryVersion, schemaHash, bundleHash, and relevant targetArtifactHash values;
• MCP response status, artifact hashes, and request timestamp;
• conversion warning codes, if present;
• coding-agent client name/version and whether it used structured output or serialized JSON text fallback.

Do not include API keys, provider credentials, tenant auth mapping, browser cookies, or canonical Connection identifiers.

Safe error behavior

Developer schema tool surfaces must fail closed:

• hidden providers look like missing providers;
• hidden operation counts are not exposed;
• hidden identifiers do not appear in error messages;
• hashes and cache keys are computed only from visibility-filtered artifacts;
• support logs redact secrets and tenant-owned identifiers.

Health and drift checks

Recommended release checks for artifact/MCP routes:

openspec validate add-developer-mcp-schema-artifacts --strict
bun run scripts/build-provider-registry.ts --check
bun run lint:registry-consistency
bun run type-check
bun run test

Route-level tests should verify:

• apifuse_dev_get_operation_spec and apifuse_dev_get_schema_bundle return the same bundleHash for the same visible operation;
• Gateway developer schema tools expose artifact hashes;
• schema bundle tools serve precomputed artifacts, not request-path conversion;
• hidden providers return public-safe not-found responses;
• developer schema tool names all start with apifuse_dev_ and remain read-only.

Escalation notes

If hashes differ between Gateway MCP developer schema tool responses for the same visible operation, treat it as drift and stop release until the canonical artifact build is regenerated or the mismatch is explained. If a public response leaks hidden provider metadata, fail closed and handle it as a security defect.