diff --git a/docs/toolhive/guides-registry/audit-logging.mdx b/docs/toolhive/guides-registry/audit-logging.mdx index 17b9185f..0a01612e 100644 --- a/docs/toolhive/guides-registry/audit-logging.mdx +++ b/docs/toolhive/guides-registry/audit-logging.mdx @@ -328,9 +328,12 @@ kubectl logs -n deployment/toolhive-registry-api \ ## Next steps -- [Configure authentication](./authentication.mdx) to ensure caller identity - appears in `subjects` -- [Configure authorization](./authorization.mdx) to control which roles can - perform which operations -- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and - metrics alongside audit logs +- [Configure telemetry](./telemetry-metrics.mdx) for metrics and distributed + tracing alongside audit logs + +## Related information + +- [Authentication](./authentication.mdx) - audit `subjects` come from the + authenticated caller identity +- [Authorization](./authorization.mdx) - controls which roles can perform the + operations you audit diff --git a/docs/toolhive/guides-registry/authentication.mdx b/docs/toolhive/guides-registry/authentication.mdx index f1922bf7..552852bd 100644 --- a/docs/toolhive/guides-registry/authentication.mdx +++ b/docs/toolhive/guides-registry/authentication.mdx @@ -1,11 +1,10 @@ --- title: Authentication configuration description: - How to configure authentication for the ToolHive Registry Server with - anonymous and OAuth modes + Configure anonymous or OAuth authentication for the ToolHive Registry Server --- -The Registry server provides secure-by-default authentication, defaulting to +The Registry Server provides secure-by-default authentication, defaulting to OAuth mode to protect your registry. You can configure authentication to fit different deployment scenarios, from development environments to production deployments with enterprise identity providers. @@ -134,9 +133,9 @@ introspection if needed. ## Kubernetes authentication -For Kubernetes deployments, you can configure OAuth to validate service account -tokens. This provides automatic, zero-config authentication for workloads -running in the cluster. +For Kubernetes deployments, you can configure OAuth to validate projected +service account tokens. This lets workloads use their Kubernetes identities +instead of separate application credentials. ### Kubernetes provider configuration @@ -520,9 +519,6 @@ providers: - [Configure authorization](./authorization.mdx) to set up role-based access control and claims-based scoping -- [Set up the database](./database.mdx) for production storage and migrations -- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and - metrics collection ## Troubleshooting diff --git a/docs/toolhive/guides-registry/authorization.mdx b/docs/toolhive/guides-registry/authorization.mdx index ed9fa238..9d71e1d5 100644 --- a/docs/toolhive/guides-registry/authorization.mdx +++ b/docs/toolhive/guides-registry/authorization.mdx @@ -5,26 +5,13 @@ description: Registry Server --- -The Registry server provides a claims-based authorization model that controls +The Registry Server provides a claims-based authorization model that controls who can manage sources, registries, and entries. Authorization builds on top of [authentication](./authentication.mdx). You need OAuth authentication enabled before configuring authorization. ## How authorization works -When a client accesses registry data, the server checks three layers in order: - -1. **Registry claims** (access gate): can the caller access this registry at - all? If the registry has claims and the caller's JWT doesn't satisfy them, - the server returns `403 Forbidden` before any data is returned. -2. **Entry claims** (visibility filter): which entries can the caller see? Each - entry can carry claims inherited from its source (for synced sources) or set - explicitly (via publish payload or Kubernetes annotation). Only entries whose - claims the caller's JWT satisfies are included in the response. -3. **Role checks** (admin operations): can the caller perform this write - operation? Publishing, deleting, and managing sources/registries require - specific [roles](#configure-roles). - When a caller makes an API request, the server: 1. Extracts the caller's claims from their JWT token @@ -44,6 +31,20 @@ flowchart LR ClaimCheck -->|No| Deny403 ``` +### Claim scopes + +Claims attach to three kinds of resource. Each scope controls a different part +of the request: + +| Scope | What its claims govern | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Registry claims** | Access to the registry's consumer API. A caller whose JWT doesn't satisfy them gets `403` on the whole `/registry/{name}` surface. | +| **Entry claims** | Per-entry visibility within a registry the caller can already reach. A consumer sees an entry only if their JWT satisfies both the registry's claims and the entry's claims. | +| **Source claims** | Admin visibility of the source, linking the source into a registry, and publishing into a managed source. Source claims never filter entries at read time. | + +See [Source claims](#source-claims) for how each source type assigns claims to +its entries. + ## Configure roles Define roles in the `auth.authz.roles` section of your configuration file. Each @@ -131,11 +132,23 @@ For synced sources (Git, API, File), claims on a source are **inherited by all entries** during sync. Every MCP server or skill ingested from that source carries the source's claims. -For Kubernetes and managed sources, source claims control who can manage the -source via the admin API but are **not** inherited by entries. Kubernetes -entries get claims from the +For Kubernetes and managed sources, source claims are **not** inherited by +entries. Kubernetes entries get claims from the [`authz-claims` annotation](./configuration.mdx#per-entry-claims-via-annotation) -on each CRD. Managed source entries get claims from the publish request payload. +on each CRD, and managed source entries get claims from the publish request +payload. + +A managed source's own claims decide who can publish into it. To publish, a +caller needs the `manageEntries` role, and their JWT must satisfy the source's +existing claims using the [visibility rule](#claim-matching-rules). A managed +source with no claims can only be published to by a super-admin. + +This check controls publishing, not entry visibility. Give the source a claim +that matches everyone who should be able to publish there, such as +`org: "acme"`. Each published entry's own claims control who can read it. + +Source claims also decide who can see and manage the source through the admin +API, and whether the source can be added to a registry. ```yaml title="config-source-claims.yaml" sources: @@ -204,10 +217,10 @@ that differ only in how they handle array-valued claims. Every check does an AND across keys (the caller must satisfy every key present on the resource), and both rules default-deny on unlabeled resources. -| Rule | Within-array test | Used for | -| -------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Visibility** | OR - the caller must share **any one** array value | Reads and access gates: list and get on sources, registries, and entries; the registry access gate on `/registry/{name}`; delete on sources, registries, and entry versions. | -| **Subset** | AND - the caller must hold **every** array value | Writes: create or update a source or registry; publish an entry; update the claims on a published entry. Applied to the **incoming** claims in the request, not to the resource's existing tags. | +| Rule | Within-array test | Used for | +| -------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Visibility** | OR - the caller must share **any one** array value | Reads and access gates: list and get on sources, registries, and entries; the registry access gate on `/registry/{name}`; publishing into a managed source; delete on sources, registries, and entry versions. | +| **Subset** | AND - the caller must hold **every** array value | Writes: create or update a source or registry; set incoming entry claims during publish; update the claims on a published entry. Applied to the **incoming** claims in the request, not to the resource's existing tags. | For scalar (string) claims the two rules behave identically. The difference only shows up on array values. @@ -280,8 +293,9 @@ on the next sync. ## Claims on published entries -When you publish an MCP server version or skill to a managed source, you can -attach claims to the entry. The server enforces three rules: +Before publishing, your JWT must satisfy the managed source's existing claims. +See [Source claims](#source-claims). The server then enforces three rules on the +entry's claims: 1. **Claims are required when authentication is enabled.** Publishing without claims, or with an empty `claims` object, against an authenticated endpoint @@ -535,8 +549,9 @@ With this configuration: - **Data team members** (JWT with `org: "acme"`, `team: "data"`) can access the `data` registry and see entries from `data-tools` and `shared`. - **Writers** in the `acme` org (JWT with `org: "acme"`, `role: "writer"`) can - publish to the `shared` managed source. The `org: "acme"` claim on the source - is what makes it reachable to non-super-admin callers under default-deny. + publish to the `shared` managed source because their JWT satisfies the + source's `org: "acme"` claim. Publishing checks that source claim, so without + it only super-admins could publish to the source (default-deny). - **Admins** (JWT with `org: "acme"`, `role: "admin"`) can manage sources and registries within the `acme` org. - **Super-admins** (JWT with `role: "super-admin"`) can access and manage @@ -551,14 +566,10 @@ that team's registry surfaces the entry. See ## Next steps -- [Configure authentication](./authentication.mdx) to set up OAuth providers -- [Configure audit logging](./audit-logging.mdx) to track who does what in the - registry -- [Configure sources and registries](./configuration.mdx) to set up your data - sources -- [Manage skills](./skills.mdx) to publish and discover reusable skills +- [Configure audit logging](./audit-logging.mdx) to record who performs which + operations ## Related information -- [Registry server introduction](./intro.mdx) - architecture and features +- [Registry Server introduction](./intro.mdx) - architecture and features overview diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 9bf04c8a..97991f0e 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -358,10 +358,11 @@ exists in the database. - `GET /registry/{registryName}/v0.1/...` - List and retrieve servers and skills - [Skills management](./skills.mdx) via the extensions API -When authentication is enabled, publish requests must include a `claims` object. -See -[Claims on published entries](./authorization.mdx#claims-on-published-entries) -for the full rules. +When authentication is enabled, the caller needs the `manageEntries` role, and +publish requests must include a `claims` object whose values are backed by a JWT +that satisfies the managed source's claims. See +[Claim scopes](./authorization.mdx#claim-scopes) for how source and entry claims +apply during publishing. See [Publish MCP servers](./publish-servers.mdx) for request examples covering publish, delete, and claims updates, or the @@ -496,7 +497,7 @@ that follows the MCP specification. Each tool definition can include: - `outputSchema`: JSON Schema describing the tool's output format - `annotations`: Additional metadata about the tool -The Registry server validates JSON syntax only. Schema validation is performed +The Registry Server validates JSON syntax only. Schema validation is performed by the operator during resource reconciliation. If the annotation contains invalid JSON, a warning is logged and the tool definitions are omitted from the registry, but the server is still registered normally. @@ -521,7 +522,7 @@ URL within the publisher-provided metadata: The registry URL from the `registry-url` annotation becomes a key in the JSON structure. -This feature requires the Registry server to be granted access to those +This feature requires the Registry Server to be granted access to those resources via a Service Account. See the [deployment section](./deploy-manual.mdx#workload-discovery) for details. @@ -708,7 +709,5 @@ precedence order. - [Publish MCP servers](./publish-servers.mdx) to a Git, file, or managed source - [Configure authentication](./authentication.mdx) to secure access to your registry -- [Set up authorization](./authorization.mdx) to control access with roles and - claims -- [Set up the database](./database.mdx) for production storage -- [Configure audit logging](./audit-logging.mdx) to track API operations +- [Configure authorization](./authorization.mdx) to control access with roles + and claims diff --git a/docs/toolhive/guides-registry/database.mdx b/docs/toolhive/guides-registry/database.mdx index 94c164c8..bbed7fc8 100644 --- a/docs/toolhive/guides-registry/database.mdx +++ b/docs/toolhive/guides-registry/database.mdx @@ -1,13 +1,16 @@ --- title: Database configuration description: - How to configure PostgreSQL database storage and migrations for the ToolHive - Registry server + Configure PostgreSQL storage, connection pooling, and migrations for the + ToolHive Registry Server --- -The Registry server requires a PostgreSQL database for storing registry state -and metadata. This enables persistence across restarts and provides a foundation -for advanced features. +The Registry Server stores registry state and metadata in a PostgreSQL database, +which persists data across restarts. The [deployment guides](./deployment.mdx) +include the minimal connection settings needed to get a server running; this +page covers the production decisions layered on top: separate migration and +application users, TLS, connection pooling, automatic migrations, and dynamic +credential mechanisms. ## Supported versions @@ -322,9 +325,8 @@ database: ## Next steps -- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and - metrics collection -- [Deploy the server](./deployment.mdx) to your Kubernetes environment +- [Configure sources and registries](./configuration.mdx) to define and evolve + your catalog ## Troubleshooting diff --git a/docs/toolhive/guides-registry/deploy-helm.mdx b/docs/toolhive/guides-registry/deploy-helm.mdx index 8d79f452..c547412b 100644 --- a/docs/toolhive/guides-registry/deploy-helm.mdx +++ b/docs/toolhive/guides-registry/deploy-helm.mdx @@ -1,8 +1,8 @@ --- title: Deploy with Helm description: - How to deploy the ToolHive Registry Server in Kubernetes using the official - Helm chart + Deploy the ToolHive Registry Server in Kubernetes using the official Helm + chart --- :::info diff --git a/docs/toolhive/guides-registry/deploy-manual.mdx b/docs/toolhive/guides-registry/deploy-manual.mdx index e7bc873d..5fab65e1 100644 --- a/docs/toolhive/guides-registry/deploy-manual.mdx +++ b/docs/toolhive/guides-registry/deploy-manual.mdx @@ -16,13 +16,22 @@ For alternative deployment approaches, see Below is an example Kubernetes Deployment configuring the ToolHive Registry Server to expose a single static registry based on a Git repository. -This example assumes that a PostgreSQL 14 or later database is available at -`db.example.com` and the necessary users for migration and application execution -are configured and able to connect to a `registry` database. It also assumes -that you have a keycloak instance configured to act as identity provider. +## Prerequisites + +- A Kubernetes cluster (current and two previous minor versions are supported) +- Permissions to create resources in the cluster +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate + with your cluster +- PostgreSQL 14 or later +- An OIDC identity provider (this example uses Keycloak) + +## Example deployment -All resources are created in the `toolhive-system` namespace. This namespace -must exist before applying the deployment. +This example assumes that the PostgreSQL database is available at +`db.example.com` and the necessary users for migration and application execution +are configured and able to connect to a `registry` database. All resources are +created in the `toolhive-system` namespace, which must exist before applying the +deployment. For further details about user grants read the [Migration user privileges](./database.mdx#migration-user-privileges) and @@ -182,7 +191,7 @@ of workloads. The types being watched are [`MCPRemoteProxy`](../guides-k8s/remote-mcp-proxy.mdx), and [`VirtualMCPServer`](../guides-vmcp/configuration.mdx). -By default, the Registry server discovers resources in all namespaces +By default, the Registry Server discovers resources in all namespaces (cluster-wide). You can restrict discovery to specific namespaces by setting the `THV_REGISTRY_WATCH_NAMESPACE` environment variable to a comma-separated list of namespace names in your deployment: @@ -392,6 +401,11 @@ re-apply it before or alongside the Deployment change. See sources and sync policies - [Set up authentication](./authentication.mdx) to secure access to your registry -- [Set up authorization](./authorization.mdx) to control access with roles and - claims - [Configure telemetry](./telemetry-metrics.mdx) to monitor your deployment + +## Related information + +- [Database configuration](./database.mdx) for the pgpass format and user + privileges +- [Quickstart: Registry Server](./quickstart.mdx) for a hands-on walkthrough of + a minimal local deployment diff --git a/docs/toolhive/guides-registry/deploy-operator.mdx b/docs/toolhive/guides-registry/deploy-operator.mdx index bfa4ce95..c609abed 100644 --- a/docs/toolhive/guides-registry/deploy-operator.mdx +++ b/docs/toolhive/guides-registry/deploy-operator.mdx @@ -1,8 +1,8 @@ --- title: Deploy with the ToolHive Operator description: - How to deploy the ToolHive Registry Server in Kubernetes using the ToolHive - Operator + Deploy the ToolHive Registry Server in Kubernetes using the deprecated + ToolHive Operator workflow --- :::warning[MCPRegistry CRD is deprecated] @@ -33,7 +33,7 @@ continue to work without changes. ## Overview -The ToolHive operator deploys the Registry server in Kubernetes by creating +The ToolHive operator deploys the Registry Server in Kubernetes by creating `MCPRegistry` resources. Alternatively, you can deploy the Registry Server manually by following the [manual deployment instructions](./deploy-manual.mdx). @@ -41,7 +41,7 @@ manually by following the [manual deployment instructions](./deploy-manual.mdx). This diagram shows the basic relationship between components. The ToolHive operator watches for `MCPRegistry` resources and automatically creates the -necessary infrastructure to run the Registry server. +necessary infrastructure to run the Registry Server. ```mermaid flowchart LR @@ -122,9 +122,9 @@ When you apply an `MCPRegistry` resource, here's what happens: 1. The ToolHive operator detects the new resource (if it's in an allowed namespace) 2. The operator creates the necessary RBAC resources in the target namespace -3. The operator creates a Deployment containing the Registry server pod and +3. The operator creates a Deployment containing the Registry Server pod and service -4. The Registry server syncs data from the configured sources +4. The Registry Server syncs data from the configured sources 5. The Registry API becomes available at the service endpoint ::: @@ -350,7 +350,7 @@ spec: ## Configure database storage -Configure PostgreSQL database storage for the Registry server. With the +Configure PostgreSQL database storage for the Registry Server. With the `configYAML` approach, database settings go directly into the config and you use `pgpassSecretRef` for password management. @@ -620,9 +620,9 @@ For detailed information about authentication configuration, including provider-specific examples for Keycloak, Auth0, Microsoft Entra ID, and Okta, see the [Authentication configuration](./authentication.mdx) guide. -## Customize the Registry server pod +## Customize the Registry Server pod -You can customize the Registry server pod using the `podTemplateSpec` field. +You can customize the Registry Server pod using the `podTemplateSpec` field. This gives you full control over the pod specification. ```yaml title="registry-custom-pod.yaml" @@ -662,7 +662,7 @@ spec: When customizing containers in `podTemplateSpec`, you must use `name: registry-api` for the main container to ensure the operator can properly -manage the Registry server. The container name is hardcoded to avoid conflict +manage the Registry Server. The container name is hardcoded to avoid conflict issues with user provided containers. Mandating a container name on the Operator side explicitly tells the Operator it is the main registry server container and any other containers provided by the user are sidecars/init containers. @@ -729,12 +729,11 @@ migration-user privileges are needed. ## Next steps -- [Configure authentication](./authentication.mdx) to secure access to your +- [Configure sources and registries](./configuration.mdx) to set up your data + sources and sync policies +- [Set up authentication](./authentication.mdx) to secure access to your registry -- [Set up authorization](./authorization.mdx) to control access with roles and - claims -- [Configure sources and registries](./configuration.mdx) for standalone - configuration reference +- [Configure telemetry](./telemetry-metrics.mdx) to monitor your deployment ## Related information diff --git a/docs/toolhive/guides-registry/deployment.mdx b/docs/toolhive/guides-registry/deployment.mdx index 92b975ac..88ee49e8 100644 --- a/docs/toolhive/guides-registry/deployment.mdx +++ b/docs/toolhive/guides-registry/deployment.mdx @@ -54,14 +54,6 @@ See [Deploy with Helm](./deploy-helm.mdx) for a complete guide. ## ToolHive Operator -:::warning[Deprecated] - -This method relies on the `MCPRegistry` CRD, which is deprecated in favor of the -[Helm](#helm) deployment method. It remains functional but will be removed in a -future release. - -::: - Deploy and manage the Registry Server using `MCPRegistry` custom resources. The ToolHive Operator watches for these resources and creates the necessary infrastructure automatically. @@ -85,13 +77,3 @@ Pick the deployment method that fits your environment and follow its guide: - [Deploy manually](./deploy-manual.mdx) for raw Kubernetes manifests - [Deploy with the ToolHive Operator](./deploy-operator.mdx) for a CRD-driven workflow (deprecated) - -Then configure the rest of the stack: - -- [Configure sources and registries](./configuration.mdx) to set up your data - sources and sync policies -- [Set up authentication](./authentication.mdx) to secure access to your - registry -- [Set up authorization](./authorization.mdx) to control access with roles and - claims -- [Configure telemetry](./telemetry-metrics.mdx) to monitor your deployment diff --git a/docs/toolhive/guides-registry/index.mdx b/docs/toolhive/guides-registry/index.mdx index ef21ff2c..6c3a3767 100644 --- a/docs/toolhive/guides-registry/index.mdx +++ b/docs/toolhive/guides-registry/index.mdx @@ -11,34 +11,15 @@ import DocCardList from '@theme/DocCardList'; The ToolHive Registry Server helps you publish and govern a catalog of MCP servers or skills for your team. Use it when you want a trusted catalog that -improves discoverability, supports publishing workflows, and gives you more -control over what different users can access. +aggregates entries from Kubernetes clusters, Git repositories, API endpoints, +and local files behind a standard MCP Registry API. -It can aggregate entries from Kubernetes clusters, Git repositories, API -endpoints, and local files, then expose them through a standard MCP Registry API -for ToolHive and other clients. - -:::note - -This section covers the **Registry Server**, a standalone service you deploy -yourself. Looking for the built-in registry instead? See +Within the ToolHive platform, the Registry Server is the self-hosted catalog +service. It is separate from the built-in registry in the ToolHive CLI and UI. +If you only need to browse the default ToolHive catalog, see [Use the registry](../guides-cli/registry.mdx) (CLI) or [Use the registry](../guides-ui/registry.mdx) (UI). -::: - -If you want to host and operate your own catalog, use the Registry Server. If -you only need to browse the default ToolHive catalog from the UI or CLI, you do -not need to deploy it. - -:::tip - -Want a web-based interface for your Registry Server catalog? The -[Cloud UI](../guides-cloud-ui/index.mdx) connects to the Registry Server and -gives your team a browsable catalog with OIDC-based authentication. - -::: - ## Where to start - **New to the Registry Server?** Follow the @@ -51,6 +32,9 @@ gives your team a browsable catalog with OIDC-based authentication. - **Already running?** Jump to [Configuration](./configuration.mdx), [Authentication](./authentication.mdx), or [Authorization](./authorization.mdx). +- **Want a web catalog?** Deploy the + [ToolHive Cloud UI](../guides-cloud-ui/index.mdx) to browse a Registry Server + catalog with OIDC-based authentication. ## Contents diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index 9e928f07..2e627b13 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -76,7 +76,7 @@ flowchart LR Git["Git"] File["File"] end - subgraph Server["Registry server"] + subgraph Server["Registry Server"] direction TB Sync["Sync manager"] Entries[("Entries")] @@ -161,20 +161,10 @@ browsing public MCP servers, but the pieces work together: `MCPServer` workloads as entries in a Registry Server through the Kubernetes source type. -If you want a private or team-scoped catalog with publishing, claims-based -access control, and multi-source aggregation, deploy a Registry Server. If you -only need to browse the public ToolHive catalog, the built-in registry is -enough. - ## Next steps +- [Follow the Registry Server quickstart](./quickstart.mdx) to deploy a local + environment and query its API +- [Choose a deployment method](./deployment.mdx) for a production environment - [Configure sources and registries](./configuration.mdx) to set up your data sources, sync policies, and entry filtering -- [Publish MCP servers](./publish-servers.mdx) to a Git, file, or managed source -- [Set up authentication](./authentication.mdx) to secure access to your - registry -- [Configure authorization](./authorization.mdx) to control access with roles - and claims -- [Manage skills](./skills.mdx) to publish and discover reusable skills -- [View the API reference](../reference/registry-api.mdx) for endpoint - documentation diff --git a/docs/toolhive/guides-registry/publish-servers.mdx b/docs/toolhive/guides-registry/publish-servers.mdx index 09fdd59e..44266fc2 100644 --- a/docs/toolhive/guides-registry/publish-servers.mdx +++ b/docs/toolhive/guides-registry/publish-servers.mdx @@ -301,8 +301,10 @@ empty array for brevity: } ``` -The publish claims must be a subset of your JWT claims, and subsequent versions -of the same server must carry the same claims as the first version. See +Publishing requires the `manageEntries` role. Your JWT must satisfy the managed +source's claims, and the publish claims must be a subset of your JWT claims. +Subsequent versions of the same server must carry the same claims as the first +version. See [Claims on published entries](./authorization.mdx#claims-on-published-entries) for the full rules. @@ -375,10 +377,8 @@ for the full authorization rules. - [Manage skills](./skills.mdx) using the same admin API for the skills extension -- [Configure authorization](./authorization.mdx) to control who can publish, - read, and update entries -- [Deploy the Cloud UI](../guides-cloud-ui/index.mdx) so your team can browse - the servers you publish from a web interface +- [Configure authentication](./authentication.mdx) to secure access to your + registry ## Related information @@ -388,3 +388,5 @@ for the full authorization rules. response schemas for every endpoint - [Configure sources and registries](./configuration.mdx) - source types, sync policies, and managed-source setup +- [Deploy the ToolHive Cloud UI](../guides-cloud-ui/index.mdx) - give your team + a browsable web catalog of the servers you publish diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx index 9603a1fd..ad1da945 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -1,8 +1,8 @@ --- title: Manage skills description: - How to publish, list, retrieve, and delete skills in the ToolHive Registry - Server through the admin API or a synced source. + Publish, list, retrieve, and delete skills in the ToolHive Registry Server + through the admin API or a synced source. --- The Registry Server exposes [skills](../concepts/skills.mdx) through an @@ -26,7 +26,7 @@ this page focuses on the admin API. ## Prerequisites -- A running Registry server with at least one **managed** source configured +- A running Registry Server with at least one **managed** source configured (required for publishing via the API; synced sources provide skills automatically) - `curl` or another HTTP client @@ -112,8 +112,10 @@ at the top level of the request body, alongside the `skill` object: } ``` -The publish claims must be a subset of your JWT claims, and all subsequent -versions of the same skill must carry the same claims as the first version. See +Publishing requires the `manageEntries` role. Your JWT must satisfy the managed +source's claims, and the publish claims must be a subset of your JWT claims. All +subsequent versions of the same skill must carry the same claims as the first +version. See [Claims on published entries](./authorization.mdx#claims-on-published-entries) for details. @@ -243,16 +245,13 @@ The API returns standard HTTP status codes: ## Next steps -- [Install skills with the CLI](../guides-cli/skills-management.mdx) to install - skills from the registry onto your local machine -- [Configure telemetry](./telemetry-metrics.mdx) to monitor your registry - deployment +- [Configure authentication](./authentication.mdx) to secure access to your + registry ## Related information - [Understanding skills](../concepts/skills.mdx) - background on the skills model -- [Registry server introduction](./intro.mdx) -- [Authentication](./authentication.mdx) - configuring API access -- [Authorization](./authorization.mdx) - role-based access control and - claims-based scoping +- [Install skills with the CLI](../guides-cli/skills-management.mdx) - install + skills from the registry onto your local machine +- [Registry Server introduction](./intro.mdx) diff --git a/docs/toolhive/guides-registry/telemetry-metrics.mdx b/docs/toolhive/guides-registry/telemetry-metrics.mdx index 7cd95711..ab6fb3ce 100644 --- a/docs/toolhive/guides-registry/telemetry-metrics.mdx +++ b/docs/toolhive/guides-registry/telemetry-metrics.mdx @@ -1,8 +1,8 @@ --- title: Telemetry and metrics description: - How to enable OpenTelemetry metrics and distributed tracing for the ToolHive - Registry Server + Enable OpenTelemetry metrics and distributed tracing for the ToolHive Registry + Server --- The ToolHive Registry Server provides comprehensive observability through @@ -189,8 +189,5 @@ traffic from application telemetry. ## Next steps -- [Deploy the server](./deployment.mdx) to your Kubernetes environment -- [Configure audit logging](./audit-logging.mdx) to capture structured API - operation events alongside your telemetry -- [Manage skills](./skills.mdx) to publish and discover reusable skills in your - registry +- [Registry Server API reference](../reference/registry-api.mdx) for the full + set of endpoints and schemas diff --git a/sidebars.ts b/sidebars.ts index bbd4c19a..2d0be563 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -251,7 +251,7 @@ const mcpSidebar: SidebarsConfig[string] = [ type: 'category', label: 'Registry Server', description: - 'How to deploy and use the ToolHive Registry server to discover and access MCP servers and skills', + 'How to deploy and use the ToolHive Registry Server to discover and access MCP servers and skills', link: { type: 'doc', id: 'toolhive/guides-registry/index', @@ -268,19 +268,19 @@ const mcpSidebar: SidebarsConfig[string] = [ }, collapsible: false, items: [ - 'toolhive/guides-registry/deploy-operator', 'toolhive/guides-registry/deploy-helm', 'toolhive/guides-registry/deploy-manual', + 'toolhive/guides-registry/deploy-operator', ], }, + 'toolhive/guides-registry/database', 'toolhive/guides-registry/configuration', 'toolhive/guides-registry/publish-servers', + 'toolhive/guides-registry/skills', 'toolhive/guides-registry/authentication', 'toolhive/guides-registry/authorization', - 'toolhive/guides-registry/database', - 'toolhive/guides-registry/skills', - 'toolhive/guides-registry/telemetry-metrics', 'toolhive/guides-registry/audit-logging', + 'toolhive/guides-registry/telemetry-metrics', 'toolhive/reference/registry-api', 'toolhive/reference/registry-schema-upstream', ],