# MCP Client Certification

Use this checklist before declaring a Topline MCP release compatible with a
real external client. Automated protocol tests remain required, but they do
not replace one browser-approved OAuth run in the actual client.

## Evidence rules

- Test a non-production fixture account with the same capability shape as a
  customer operator.
- Record client name/version, Topline MCP server version, product route,
  transport, date, and pass/fail result.
- Never copy access tokens, refresh tokens, authorization codes, PKCE
  verifiers, cookies, or verification codes into the evidence record.
- A source commit, HTTP health response, or successful OAuth consent screen is
  not proof that a client can discover and invoke tools.

## Product matrix

Run each row for Codex and Claude Code. Add Cursor or another client when that
client's current MCP transport and OAuth support matches the product route.

| Product | Required path | Required proof |
| --- | --- | --- |
| Build | Local stdio package delegates to `/mcp/build` | OAuth approval, isolated Build catalog, stdio `platform_connection_check`, offline local inspection, deterministic bundle identity, portable local-folder deploy, phase progress, trusted validation, guarded disposable-draft deletion, and expected denial for a Workspace-only tool. |
| Workspace | Streamable HTTP at `/mcp/workspace` | OAuth approval, isolated Workspace catalog, `platform_connection_check`, documentation read, tenant-bound workspace discovery, conversation search/read pagination, and expected denial for a Build-only tool. |
| Legacy compatibility | Streamable HTTP at `/mcp/harness` | Existing client still initializes; response includes deprecation and successor links; new setup documentation does not point here. |

## Required scenarios

1. Start with no saved Topline authorization and complete browser OAuth with
   PKCE from the client.
2. Confirm `tools/list` contains only the selected product's tools and only
   tools permitted by the approved scopes and current Topline capabilities.
3. In Developer Access, choose **Verify connection**, run the generated
   `platform_connection_check` request in the same client, and confirm Topline
   reports `verified` for the expected product and client.
4. Run one representative read-only tool and confirm Developer Access updates
   the exact authorization's call count, latency, last-success time, and tool.
5. List workspaces, exercise a cursor page for `search_conversations`, then a
   cursor page for `read_conversation`; confirm older messages are returned
   without tool payloads and oversized messages carry `truncated: true`.
6. Revoke the tested authorization in Developer Access. Confirm both access
   and refresh stop working, then reconnect through a fresh OAuth approval.
7. Repeat with an expired access token and valid refresh token, a denied scope,
   a cross-product audience, an invalid verification code, and an expired
   verification code.
8. For Build, inspect the same fixture twice and require an identical bundle
   hash without any remote request. Then deploy it once from an
   `artifact-apps/<name>` folder and once from an arbitrary folder whose
   manifest id differs from the folder name. Confirm the logical source root,
   phase progress, and trusted validation result.
9. Confirm draft cleanup rejects an incorrect confirmation id, a different MCP
   connection, an in-flight deploy, and any promoted/live artifact. Then delete
   only the disposable unpromoted draft with an exact matching id.

## Release record

Store the completed matrix with the release ticket. Mark each row as
`passed`, `failed`, or `not supported by this client`, and link sanitized logs
or screenshots. Publication and customer rollout remain separate approvals
after certification passes.