Create an MCP server
/api/v1/mcp-serversRegister a remote HTTPS MCP server for later attachment to a compatible agent. The connector credential is encrypted at rest and is never returned; responses contain only a masked hint.
Registration does not imply runtime support. Before attaching the returned ID, read the selected deployment's supports_mcp field from GET /api/v1/models; unsupported combinations fail closed when the agent is saved or admitted.
Required access
Credentials: delegated token, user session
Scope: mcp_servers:create
A delegated token can create only a private connector owned by its user. Publishing to the organization library remains an admin action performed through a direct user session.
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 payload for creating an MCP server.
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" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "incident_catalog", "description": "Read-only incident and service catalog tools.", "url": "https://mcp.example.com/mcp", "transport": "streamable_http", "auth_type": "oauth_token", "auth_token": "replace-with-a-scoped-token", "tool_filter": { "default_enabled": false, "allowed_tools": [ "search_incidents", "get_service" ], "blocked_tools": [] }, "require_approval": "never", "visibility": "private" }'{ "mcp_server": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "visibility": "org_shared", "published_at": "2019-08-24T14:15:22Z", "name": "string", "slug": "string", "description": "string", "url": "string", "transport": "sse", "auth_type": "none", "auth_hint": "string", "tool_filter": { "default_enabled": true, "allowed_tools": [ "string" ], "blocked_tools": [ "string" ] }, "require_approval": "always", "is_active": true, "discovered_tools": [ { "name": "string", "description": "string" } ], "tools_synced_at": "2019-08-24T14:15:22Z", "blocked_by_egress": false, "blocked_reason": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}{ "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"}List MCP servers GET
List remote MCP connector registrations visible to the delegated user. Use `scope=private` for that user's connectors or `scope=library` for connectors published to the organization.
Test an MCP server connection POST
Run 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.