Skip to content

Add an MCP initialize readiness check - #6374

Open
Whxuan0701 wants to merge 2 commits into
stacklok:mainfrom
Whxuan0701:pr/mcp-initialize-check
Open

Add an MCP initialize readiness check#6374
Whxuan0701 wants to merge 2 commits into
stacklok:mainfrom
Whxuan0701:pr/mcp-initialize-check

Conversation

@Whxuan0701

@Whxuan0701 Whxuan0701 commented Aug 19, 2026

Copy link
Copy Markdown

Summary

Agent harnesses and CI need a protocol-level readiness signal, but thv mcp list performs capability enumeration after initialize and is unsuitable for servers that intentionally expose no tools, resources, or prompts. A lightweight preflight should validate the MCP session handshake itself.

  • Add thv mcp check with auto, SSE, and streamable HTTP transport support.
  • Perform only transport setup, initialize, and connection close.
  • Report negotiated protocol/server/capability metadata as text or JSON and return a non-zero exit code on failure.
  • Keep check-specific flags isolated from sibling MCP commands and route output through Cobra writers.

Type of change

  • Bug fix
  • New feature
  • Refactoring (no behavior change)
  • Dependency update
  • Documentation
  • Other (describe):

Test plan

  • Unit tests (task -t Taskfile.focused.yml test, using the repository's -race and linker settings for ./pkg/mcp/client and ./cmd/thv/app)
  • E2E tests (task test-e2e)
  • Linting (task lint-fix)
  • Manual testing (describe below)

Regenerated all CLI, Swagger, and Helm documentation with task docs, then verified the CLI documentation byte-for-byte against a fresh go run cmd/help/main.go output directory.

API Compatibility

  • This PR does not break the v1beta1 API.

Changes

File Change
pkg/mcp/client/client.go Add a Probe API that returns initialize metadata and the selected transport without enumerating capabilities.
pkg/mcp/client/client_test.go Exercise a real streamable HTTP MCP server and assert that the probe sends initialize but no list methods.
cmd/thv/app/mcp_check.go Add the command with isolated flags, timeout handling, and text/JSON output through Cobra writers.
cmd/thv/app/mcp_check_test.go Verify the five-second default survives parent-command construction and JSON is capturable through the command writer.
cmd/thv/app/mcp.go Register the new command.
docs/cli/thv_mcp_check.md Document the generated CLI workflow and flags.
docs/cli/thv_mcp.md Link the new command from the generated parent command reference.

Does this introduce a user-facing change?

Yes. Users can now use thv mcp check --server ... --format json as an MCP-native readiness gate for CI, GitOps, and Agent harnesses.

Special notes for reviewers

The new probe intentionally does not call tools/list, resources/list, prompts/list, or any tool. Existing Connect callers retain their behavior and API.

Expose a protocol-level preflight for Agent harnesses and CI. The check performs only transport setup and the MCP initialize handshake, then reports negotiated metadata without enumerating or invoking capabilities.

Signed-off-by: XD <xd@XDdeMacBook-Pro.local>
Keep mcp check flags isolated from sibling commands and route text and JSON results through Cobra output writers. Add real initialize-only and CLI regression coverage, then regenerate the command documentation.

Signed-off-by: XD <xd@XDdeMacBook-Pro.local>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant