Test an MCP server connection
/api/v1/mcp-servers/testRun an advisory backend-originated MCP initialize and tools/list probe. A successful result proves that Guest Machines can reach and authenticate to the endpoint; it does not prove that a model provider can reach it or that any production model currently supports hosted MCP.
Required access
Credentials: delegated token, user session
Scope: mcp_servers:edit
When server_id is supplied without auth_token, the caller must have edit authority for that connector: its private owner or a direct-session organization admin/owner for a library connector. Delegated tokens and read-only library visibility cannot exercise a stored organization secret. The credential is reused only for the exact saved URL; testing a changed URL requires re-entering the token.
Authorization
DelegatedToken A token issued to an external application acting for a specific user, prefixed gsmc_dt_. Carries that user's identity for attribution and ownership, is bound to the organization chosen when it was issued, and stays capped at member role however privileged the user is.
In: header
Header Parameters
Selects the active organization for a direct user session that has more than one membership. Service-principal keys and delegated tokens are each bound to one organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request to probe an MCP server's reachability (initialize + tools/list).
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/mcp-servers/test" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://mcp.example.com/mcp", "transport": "streamable_http", "auth_type": "oauth_token", "auth_token": "replace-with-a-scoped-token" }'{ "ok": true, "server_name": "string", "server_version": "string", "tool_count": 0, "tools": [ { "name": "string", "description": "string" } ], "error": "string", "error_kind": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}