--- title: "Get a server from a registry" method: GET path: "/api/v1beta/registry/{name}/servers/{serverName}" tags: ["registry"] --- # Get a server from a registry `GET /api/v1beta/registry/{name}/servers/{serverName}` Get details of a specific server in a registry ## Path parameters - `name` string, required - `serverName` string, required ## Response `200` OK - PkgApiV1GetServerResponse — Response containing server details - `is_remote` boolean — Indicates if this is a remote server - `remote_server` RegistryRemoteServerMetadata — Remote server details (if it's a remote server) - `custom_metadata` object — CustomMetadata allows for additional user-defined metadata - `description` string — Description is a human-readable description of the server's purpose and functionality - `env_vars` RegistryEnvVar[] — EnvVars defines environment variables that can be passed to configure the client These might be needed for client-side configuration when connecting to the remote server - `default` string — Default is the value to use if the environment variable is not explicitly provided Only used for non-required variables - `description` string — Description is a human-readable explanation of the variable's purpose - `name` string — Name is the environment variable name (e.g., API_KEY) - `required` boolean — Required indicates whether this environment variable must be provided If true and not provided via command line or secrets, the user will be prompted for a value - `secret` boolean — Secret indicates whether this environment variable contains sensitive information If true, the value will be stored as a secret rather than as a plain environment variable - `headers` RegistryHeader[] — Headers defines HTTP headers that can be passed to the remote server for authentication These are used with the thv proxy command's authentication features - `choices` string[] — Choices provides a list of valid values for the header (optional) - `default` string — Default is the value to use if the header is not explicitly provided Only used for non-required headers - `description` string — Description is a human-readable explanation of the header's purpose - `name` string — Name is the header name (e.g., X-API-Key, Authorization) - `required` boolean — Required indicates whether this header must be provided If true and not provided via command line or secrets, the user will be prompted for a value - `secret` boolean — Secret indicates whether this header contains sensitive information If true, the value will be stored as a secret rather than as plain text - `metadata` RegistryMetadata — Metadata contains additional information about the server such as popularity metrics - `kubernetes` RegistryKubernetesMetadata — Kubernetes contains Kubernetes-specific metadata when the MCP server is deployed in a cluster. This field is optional and only populated when: - The server is served from ToolHive Registry Server - The server was auto-discovered from a Kubernetes deployment - The Kubernetes resource has the required registry annotations - `image` string — Image is the container image used by the Kubernetes workload (applicable to MCPServer) - `kind` string — Kind is the Kubernetes resource kind (e.g., MCPServer, VirtualMCPServer, MCPRemoteProxy) - `name` string — Name is the Kubernetes resource name - `namespace` string — Namespace is the Kubernetes namespace where the resource is deployed - `transport` string — Transport is the transport type configured for the Kubernetes workload (applicable to MCPServer) - `uid` string — UID is the Kubernetes resource UID - `last_updated` string — LastUpdated is the timestamp when the server was last updated, in RFC3339 format - `stars` integer — Stars represents the popularity rating or number of stars for the server - `name` string — Name is the identifier for the MCP server, used when referencing the server in commands If not provided, it will be auto-generated from the registry key - `oauth_config` RegistryOAuthConfig — OAuthConfig provides OAuth/OIDC configuration for authentication to the remote server Used with the thv proxy command's --remote-auth flags - `authorize_url` string — AuthorizeURL is the OAuth authorization endpoint URL Used for non-OIDC OAuth flows when issuer is not provided - `callback_port` integer — CallbackPort is the specific port to use for the OAuth callback server If not specified, a random available port will be used - `client_id` string — ClientID is the OAuth client ID for authentication - `issuer` string — Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com) Used for OIDC discovery to find authorization and token endpoints - `oauth_params` object — OAuthParams contains additional OAuth parameters to include in the authorization request These are server-specific parameters like "prompt", "response_mode", etc. - `resource` string — Resource is the OAuth 2.0 resource indicator (RFC 8707) - `scopes` string[] — Scopes are the OAuth scopes to request If not specified, defaults to ["openid", "profile", "email"] for OIDC - `token_url` string — TokenURL is the OAuth token endpoint URL Used for non-OIDC OAuth flows when issuer is not provided - `use_pkce` boolean — UsePKCE indicates whether to use PKCE for the OAuth flow Defaults to true for enhanced security - `overview` string — Overview is a longer Markdown-formatted description for web display. Unlike the Description field (limited to 500 chars), this supports full Markdown and is intended for rich rendering on catalog pages. - `proxy_port` integer — ProxyPort is the port for the HTTP proxy to listen on (host port) If not specified, a random available port will be assigned - `repository_url` string — RepositoryURL is the URL to the source code repository for the server - `stateless` boolean — Stateless indicates the server only supports POST (no SSE/GET) - `status` string — Status indicates whether the server is currently active or deprecated - `tags` string[] — Tags are categorization labels for the server to aid in discovery and filtering - `tier` string — Tier represents the tier classification level of the server, e.g., "Official" or "Community" - `title` string — Title is an optional human-readable display name for the server. If not provided, the Name field is used for display purposes. - `tools` string[] — Tools is a list of tool names provided by this MCP server - `transport` string — Transport defines the communication protocol for the server For containers: stdio, sse, or streamable-http For remote servers: sse or streamable-http (stdio not supported) - `url` string — URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp) - `server` RegistryImageMetadata — Container server details (if it's a container server) - `args` string[] — Args are the default command-line arguments to pass to the MCP server container. These arguments will be used only if no command-line arguments are provided by the user. If the user provides arguments, they will override these defaults. - `custom_metadata` object — CustomMetadata allows for additional user-defined metadata - `description` string — Description is a human-readable description of the server's purpose and functionality - `docker_tags` string[] — DockerTags lists the available Docker tags for this server image - `env_vars` RegistryEnvVar[] — EnvVars defines environment variables that can be passed to the server - `default` string — Default is the value to use if the environment variable is not explicitly provided Only used for non-required variables - `description` string — Description is a human-readable explanation of the variable's purpose - `name` string — Name is the environment variable name (e.g., API_KEY) - `required` boolean — Required indicates whether this environment variable must be provided If true and not provided via command line or secrets, the user will be prompted for a value - `secret` boolean — Secret indicates whether this environment variable contains sensitive information If true, the value will be stored as a secret rather than as a plain environment variable - `image` string — Image is the Docker image reference for the MCP server - `metadata` RegistryMetadata — Metadata contains additional information about the server such as popularity metrics - `kubernetes` RegistryKubernetesMetadata — Kubernetes contains Kubernetes-specific metadata when the MCP server is deployed in a cluster. This field is optional and only populated when: - The server is served from ToolHive Registry Server - The server was auto-discovered from a Kubernetes deployment - The Kubernetes resource has the required registry annotations - `image` string — Image is the container image used by the Kubernetes workload (applicable to MCPServer) - `kind` string — Kind is the Kubernetes resource kind (e.g., MCPServer, VirtualMCPServer, MCPRemoteProxy) - `name` string — Name is the Kubernetes resource name - `namespace` string — Namespace is the Kubernetes namespace where the resource is deployed - `transport` string — Transport is the transport type configured for the Kubernetes workload (applicable to MCPServer) - `uid` string — UID is the Kubernetes resource UID - `last_updated` string — LastUpdated is the timestamp when the server was last updated, in RFC3339 format - `stars` integer — Stars represents the popularity rating or number of stars for the server - `name` string — Name is the identifier for the MCP server, used when referencing the server in commands If not provided, it will be auto-generated from the registry key - `overview` string — Overview is a longer Markdown-formatted description for web display. Unlike the Description field (limited to 500 chars), this supports full Markdown and is intended for rich rendering on catalog pages. - `permissions` PermissionsProfile — Permission profile to apply - `name` string — Name is the name of the profile - `network` PermissionsNetworkPermissions — Network defines network permissions - `inbound` PermissionsInboundNetworkPermissions — Inbound defines inbound network permissions - `allow_host` string[] — AllowHost is a list of allowed hosts for inbound connections - `mode` string — Mode specifies the network mode for the container (e.g., "host", "bridge", "none") When empty, the default container runtime network mode is used - `outbound` PermissionsOutboundNetworkPermissions — Outbound defines outbound network permissions - `allow_host` string[] — AllowHost is a list of allowed hosts - `allow_port` integer[] — AllowPort is a list of allowed ports - `insecure_allow_all` boolean — InsecureAllowAll allows all outbound network connections - `privileged` boolean — Privileged indicates whether the container should run in privileged mode When true, the container has access to all host devices and capabilities Use with extreme caution as this removes most security isolation - `read` string[] — Read is a list of mount declarations that the container can read from These can be in the following formats: - A single path: The same path will be mounted from host to container - host-path:container-path: Different paths for host and container - resource-uri:container-path: Mount a resource identified by URI to a container path - `write` string[] — Write is a list of mount declarations that the container can write to These follow the same format as Read mounts but with write permissions - `provenance` RegistryProvenance — Provenance is the expected signer identity for this skill, checked on first install instead of trust-on-first-use. Absent means unconstrained — most catalog entries won't have this for a while, and that must not break installs; it's an opt-in tightening per entry, not a requirement. Each field constrains independently, and an empty string leaves that dimension unconstrained. Attestation is the exception: setting it at all, even to an empty struct, requires the artifact to be attested, so verification fails against a signature carrying no statement. Its own PredicateType and Predicate then follow the usual rule and constrain only when set. Predicate must be a JSON object; anything else can never match, and Validate rejects it rather than letting it through as a constraint that silently fails every artifact. - `attestation` RegistryVerifiedAttestation - `predicate` unknown - `predicate_type` string - `cert_issuer` string - `repository_ref` string - `repository_uri` string - `runner_environment` string - `signer_identity` string - `sigstore_url` string - `proxy_port` integer — ProxyPort is the port for the HTTP proxy to listen on (host port) If not specified, a random available port will be assigned - `repository_url` string — RepositoryURL is the URL to the source code repository for the server - `stateless` boolean — Stateless indicates the server only supports POST (no SSE/GET) - `status` string — Status indicates whether the server is currently active or deprecated - `tags` string[] — Tags are categorization labels for the server to aid in discovery and filtering - `target_port` integer — TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports) - `tier` string — Tier represents the tier classification level of the server, e.g., "Official" or "Community" - `title` string — Title is an optional human-readable display name for the server. If not provided, the Name field is used for display purposes. - `tools` string[] — Tools is a list of tool names provided by this MCP server - `transport` string — Transport defines the communication protocol for the server For containers: stdio, sse, or streamable-http For remote servers: sse or streamable-http (stdio not supported) ## Other responses - `404` — Not Found ## Changes > 49 revisions in range; 6 could not be searched. - **2026-06-25** `eca05ec353c1` — 2 info - added the optional property `remote_server/stateless` to the response with the `200` status - added the optional property `server/stateless` to the response with the `200` status - **2026-03-17** `8ab2f5690c97` — 2 info - added the optional property `remote_server` to the response with the `200` status - added the optional property `server` to the response with the `200` status - **2026-03-03** `3e1a5843166a` — 2 warning - removed the optional property `remote_server` from the response with the `200` status - removed the optional property `server` from the response with the `200` status - **2026-02-20** `cb830b4f4217` — 2 warning, 4 info - removed the optional property `remote_server/metadata/pulls` from the response with the `200` status - removed the optional property `server/metadata/pulls` from the response with the `200` status - added the optional property `remote_server/overview` to the response with the `200` status - added the optional property `remote_server/title` to the response with the `200` status - …2 more - **2026-02-09** `a00c1abcef71` — 2 info - added the optional property `remote_server/metadata/kubernetes` to the response with the `200` status - added the optional property `server/metadata/kubernetes` to the response with the `200` status [Full history](https://skmtc.dev/stacklok/apis/toolhive-api/changes/api/v1beta/registry/:name/servers/:serverName/get.md) --- [API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/e9f942effcda/schema)