Skip to content

Commit 99e718c

Browse files
Altamimi-DevAltamimi-Dev
committed
feat: add MCP handshake test mode to Test Connection
UI half of the MCP handshake test, split out of IBM/mcp-context-forge#5934 now that the client lives in this repo. Test Connection gains a mode toggle. HTTP request keeps the existing raw-request behavior; MCP handshake calls the new POST /v1/mcp-servers/test-handshake and reports whether the target actually speaks MCP: - Detail rows for server name/version, protocol version, negotiation path (server/discover or initialize) and credential source - Count badges for first-page tools/resources/prompts, rendered as "3+ tools" when countsPartial marks the listing truncated - A failure-class badge (transport / protocol negotiation / authentication / invalid response) with the backend's actionable copy - A collapsible raw-response preview - Method, content type and body inputs are hidden in handshake mode; the in-flight request is aborted on unmount, cancel, and mode switch New user-facing copy goes through react-intl, with keys added to the en-US, es-ES and pt-BR mcpServer namespaces. The en-US messages are byte-identical to the strings they replace. Component counts use ICU plural forms. openapi.json gains only the new /v1/mcp-servers/test-handshake path plus the GatewayHandshakeRequest/GatewayHandshakeResponse schemas, extracted from the gateway's app.openapi(). The snapshot stays pinned at API v1.0.7 otherwise, so the generated types pick up the handshake endpoint without dragging in unrelated spec drift. Relates to IBM/mcp-context-forge#5649 Signed-off-by: Ahmad Al Tamimi <altamimi.dev@gmail.com>
1 parent 2bdbc30 commit 99e718c

7 files changed

Lines changed: 845 additions & 71 deletions

File tree

‎openapi.json‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36803,6 +36803,89 @@
3680336803
}
3680436804
]
3680536805
}
36806+
},
36807+
"/v1/mcp-servers/test-handshake": {
36808+
"post": {
36809+
"tags": [
36810+
"MCP Servers"
36811+
],
36812+
"summary": "Check Mcp Server Handshake",
36813+
"description": "Test whether an MCP server URL speaks MCP via a protocol handshake.\n\nDelegates to ``test_gateway_handshake`` in\n``mcpgateway.services.gateway_service``, which tries the stateless\n``server/discover`` method first and falls back to a stateful SDK\n``initialize`` round-trip, classifying failures for actionable UI copy.\n\nArgs:\n request (GatewayHandshakeRequest): The request object containing the server URL and optional headers.\n team_id (Optional[str]): Optional team ID for team-specific gateways.\n user: Authenticated user context.\n db (Session): Database session dependency.\n\nReturns:\n GatewayHandshakeResponse: The handshake outcome, including negotiation path,\n server identity, capabilities, component counts, and failure classification.\n\nExamples:\n >>> callable(check_mcp_server_handshake)\n True\n >>> check_mcp_server_handshake.__name__\n 'check_mcp_server_handshake'",
36814+
"operationId": "check_mcp_server_handshake_v1_mcp_servers_test_handshake_post",
36815+
"security": [
36816+
{
36817+
"ConfigurableHTTPBearer": []
36818+
}
36819+
],
36820+
"parameters": [
36821+
{
36822+
"name": "team_id",
36823+
"in": "query",
36824+
"required": false,
36825+
"schema": {
36826+
"anyOf": [
36827+
{
36828+
"type": "string"
36829+
},
36830+
{
36831+
"type": "null"
36832+
}
36833+
],
36834+
"description": "Filter by team ID",
36835+
"title": "Team Id"
36836+
},
36837+
"description": "Filter by team ID"
36838+
},
36839+
{
36840+
"name": "jwt_token",
36841+
"in": "cookie",
36842+
"required": false,
36843+
"schema": {
36844+
"anyOf": [
36845+
{
36846+
"type": "string"
36847+
},
36848+
{
36849+
"type": "null"
36850+
}
36851+
],
36852+
"title": "Jwt Token"
36853+
}
36854+
}
36855+
],
36856+
"requestBody": {
36857+
"required": true,
36858+
"content": {
36859+
"application/json": {
36860+
"schema": {
36861+
"$ref": "#/components/schemas/GatewayHandshakeRequest"
36862+
}
36863+
}
36864+
}
36865+
},
36866+
"responses": {
36867+
"200": {
36868+
"description": "Successful Response",
36869+
"content": {
36870+
"application/json": {
36871+
"schema": {
36872+
"$ref": "#/components/schemas/GatewayHandshakeResponse"
36873+
}
36874+
}
36875+
}
36876+
},
36877+
"422": {
36878+
"description": "Validation Error",
36879+
"content": {
36880+
"application/json": {
36881+
"schema": {
36882+
"$ref": "#/components/schemas/HTTPValidationError"
36883+
}
36884+
}
36885+
}
36886+
}
36887+
}
36888+
}
3680636889
}
3680736890
},
3680836891
"components": {
@@ -52526,6 +52609,203 @@
5252652609
"type"
5252752610
],
5252852611
"title": "ValidationError"
52612+
},
52613+
"GatewayHandshakeRequest": {
52614+
"properties": {
52615+
"baseUrl": {
52616+
"type": "string",
52617+
"minLength": 1,
52618+
"format": "uri",
52619+
"title": "Baseurl",
52620+
"description": "Base URL of the MCP server to test"
52621+
},
52622+
"path": {
52623+
"anyOf": [
52624+
{
52625+
"type": "string"
52626+
},
52627+
{
52628+
"type": "null"
52629+
}
52630+
],
52631+
"title": "Path",
52632+
"description": "Optional path appended to the base URL"
52633+
},
52634+
"headers": {
52635+
"anyOf": [
52636+
{
52637+
"additionalProperties": {
52638+
"type": "string"
52639+
},
52640+
"type": "object"
52641+
},
52642+
{
52643+
"type": "null"
52644+
}
52645+
],
52646+
"title": "Headers",
52647+
"description": "Optional headers (e.g. Authorization) sent with the handshake"
52648+
}
52649+
},
52650+
"type": "object",
52651+
"required": [
52652+
"baseUrl"
52653+
],
52654+
"title": "GatewayHandshakeRequest",
52655+
"description": "Request to run an MCP handshake test against a server URL.",
52656+
"nullable": true
52657+
},
52658+
"GatewayHandshakeResponse": {
52659+
"properties": {
52660+
"success": {
52661+
"type": "boolean",
52662+
"title": "Success"
52663+
},
52664+
"latencyMs": {
52665+
"type": "integer",
52666+
"title": "Latencyms"
52667+
},
52668+
"negotiationPath": {
52669+
"anyOf": [
52670+
{
52671+
"type": "string",
52672+
"enum": [
52673+
"server_discover",
52674+
"initialize"
52675+
]
52676+
},
52677+
{
52678+
"type": "null"
52679+
}
52680+
],
52681+
"title": "Negotiationpath",
52682+
"description": "Which handshake path produced the result"
52683+
},
52684+
"protocolVersion": {
52685+
"anyOf": [
52686+
{
52687+
"type": "string"
52688+
},
52689+
{
52690+
"type": "null"
52691+
}
52692+
],
52693+
"title": "Protocolversion"
52694+
},
52695+
"serverName": {
52696+
"anyOf": [
52697+
{
52698+
"type": "string"
52699+
},
52700+
{
52701+
"type": "null"
52702+
}
52703+
],
52704+
"title": "Servername"
52705+
},
52706+
"serverVersion": {
52707+
"anyOf": [
52708+
{
52709+
"type": "string"
52710+
},
52711+
{
52712+
"type": "null"
52713+
}
52714+
],
52715+
"title": "Serverversion"
52716+
},
52717+
"capabilities": {
52718+
"anyOf": [
52719+
{
52720+
"additionalProperties": true,
52721+
"type": "object"
52722+
},
52723+
{
52724+
"type": "null"
52725+
}
52726+
],
52727+
"title": "Capabilities"
52728+
},
52729+
"componentCounts": {
52730+
"anyOf": [
52731+
{
52732+
"additionalProperties": {
52733+
"type": "integer"
52734+
},
52735+
"type": "object"
52736+
},
52737+
{
52738+
"type": "null"
52739+
}
52740+
],
52741+
"title": "Componentcounts",
52742+
"description": "Counts for tools/resources/prompts; a key is absent when the capability is not advertised"
52743+
},
52744+
"countsPartial": {
52745+
"type": "boolean",
52746+
"title": "Countspartial",
52747+
"description": "True when any list result had a nextCursor (counts are first-page lower bounds)",
52748+
"default": false
52749+
},
52750+
"credentialSource": {
52751+
"type": "string",
52752+
"enum": [
52753+
"stored",
52754+
"form",
52755+
"none"
52756+
],
52757+
"title": "Credentialsource",
52758+
"default": "none"
52759+
},
52760+
"failureClass": {
52761+
"anyOf": [
52762+
{
52763+
"type": "string",
52764+
"enum": [
52765+
"transport",
52766+
"protocol",
52767+
"auth",
52768+
"invalid_response"
52769+
]
52770+
},
52771+
{
52772+
"type": "null"
52773+
}
52774+
],
52775+
"title": "Failureclass"
52776+
},
52777+
"error": {
52778+
"anyOf": [
52779+
{
52780+
"type": "string"
52781+
},
52782+
{
52783+
"type": "null"
52784+
}
52785+
],
52786+
"title": "Error"
52787+
},
52788+
"rawPreview": {
52789+
"anyOf": [
52790+
{
52791+
"type": "string"
52792+
},
52793+
{
52794+
"type": "null"
52795+
}
52796+
],
52797+
"title": "Rawpreview",
52798+
"description": "Size-capped JSON preview of the final handshake payload"
52799+
}
52800+
},
52801+
"type": "object",
52802+
"required": [
52803+
"success",
52804+
"latencyMs"
52805+
],
52806+
"title": "GatewayHandshakeResponse",
52807+
"description": "Result of an MCP handshake test.",
52808+
"nullable": true
5252952809
}
5253052810
},
5253152811
"securitySchemes": {

‎src/api/servers.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,12 @@
77

88
import { api } from "./client";
99
import type { ServersResponse, MCPServer } from "../types/server";
10-
import type { GatewayTestRequest, GatewayTestResponse } from "@/generated/types";
10+
import type {
11+
GatewayHandshakeRequest,
12+
GatewayHandshakeResponse,
13+
GatewayTestRequest,
14+
GatewayTestResponse,
15+
} from "@/generated/types";
1116

1217
const serverByIdRequestCache = new Map<string, Promise<MCPServer>>();
1318

@@ -130,6 +135,19 @@ export const serversApi = {
130135
return api.post("/v1/mcp-servers/test", request, { signal });
131136
},
132137

138+
/**
139+
* Test whether an MCP server URL speaks MCP via a protocol handshake.
140+
*
141+
* Tries the stateless server/discover method (MCP 2026-07-28+) first and
142+
* falls back to a stateful initialize round-trip for earlier specs.
143+
*/
144+
testHandshake: (
145+
request: GatewayHandshakeRequest,
146+
signal?: AbortSignal,
147+
): Promise<GatewayHandshakeResponse> => {
148+
return api.post("/v1/mcp-servers/test-handshake", request, { signal });
149+
},
150+
133151
/**
134152
* Toggle the enabled state of an MCP server (activate/deactivate)
135153
*/

0 commit comments

Comments
 (0)