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

Assistant setup handoff

Developer Access opens a task menu: Connect an AI assistant, Connected tools, and Developer credentials. Back returns to the menu without discarding setup choices or unfinished tool forms. OAuth/artifact handoffs open Connected tools. Personal Drive/Calendar access and fingerprint verification live on Profile; legacy callback links redirect there.

Choose Connect an AI assistant, select a client, and expand Topline Build MCP or Topline Workspace MCP. The setup offers Send setup to ChatGPT, Open in Claude Code, and Copy message for each product. View setup message exposes the exact text before opening the assistant. Clipboard failure reveals and focuses that text for manual copying. Codex configuration remains under the client selector.

• ChatGPT uses https://chatgpt.com/?q=.... A browser check on 2026-09-16 showed that navigation sent the query, including with submit=false; the button and adjacent copy therefore describe sending, not an unsent draft. Recheck this behavior when certifying the handoff. The message still requires the user to add the MCP connection and approve OAuth under their account/workspace policy.
• Claude Code uses the documented claude-cli://open?q=... scheme (2.1.91+). It prefills an unsent prompt without choosing a local directory. The message asks for the project and installation scope before configuration changes. See Claude Code deep links.
• Claude Code Build setup retains the local @topline-build/harness-mcp stdio package. Workspace uses HTTP. ChatGPT Build setup is explicitly limited to hosted tools, with local-folder work directed to Claude Code or Codex.
• Launch URLs include only the public product endpoint and setup instructions. They exclude tokens, saved client configuration, account data, and verification challenges. Credential-bearing or malformed endpoints do not get launch links.
• Opening or copying a message must not mark a connection verified. After OAuth, the user creates the existing one-time Verify connection challenge, copies the check into the client, and checks its result in Topline.

Check both product messages, client switching, keyboard access, narrow layouts, clipboard denial, and a machine without the Claude Code URL handler. A successful launch is not a completed MCP client certification; run the scenarios below.

MCP connection and tools

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.