Skip to content

Registry server documentation for v0.6.0 #549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rdimitrov merged 3 commits into from
Feb 13, 2026
Merged

Registry server documentation for v0.6.0 #549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0351671
Registry server documentation for v0.6.0
rdimitrov Feb 11, 2026
2d2761b
Address the items flagged by the docs-review skill
rdimitrov Feb 12, 2026
a57af24
Remove implications that the db is optional
rdimitrov Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/toolhive/guides-k8s/deploy-registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ description:
with your cluster
- The ToolHive operator installed in your cluster (see
[Deploy the operator](./deploy-operator.mdx))
- A PostgreSQL database (recommended for production deployments)
- A PostgreSQL database

## Overview

Expand Down Expand Up @@ -281,8 +281,7 @@ spec:

## Configure database storage

For production deployments, configure PostgreSQL database storage for
persistence across restarts.
Configure PostgreSQL database storage for the Registry server.

```yaml {17-32} title="registry-with-database.yaml"
apiVersion: v1
Expand Down
46 changes: 28 additions & 18 deletions docs/toolhive/guides-registry/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ registries:
auth:
mode: anonymous

# Optional: Database configuration
# Database configuration (required)
database:
host: localhost
port: 5432
Expand All @@ -54,14 +54,20 @@ database:
maxOpenConns: 25
maxIdleConns: 5
connMaxLifetime: '5m'
maxMetaSize: 65536
# Optional: dynamic authentication (alternative to pgpass)
# dynamicAuth:
# awsRdsIam:
# region: us-east-1
```

## Command-line flags

| Flag | Description | Required | Default |
| ----------- | ------------------------------- | -------- | ------- |
| `--config` | Path to YAML configuration file | Yes | - |
| `--address` | Server listen address | No | `:8080` |
| Flag | Description | Required | Default |
| ------------- | ------------------------------------------- | -------- | ------- |
| `--config` | Path to YAML configuration file | Yes | - |
| `--address` | Server listen address | No | `:8080` |
| `--auth-mode` | Override auth mode (`anonymous` or `oauth`) | No | - |

## Registry data formats

Expand Down Expand Up @@ -101,7 +107,11 @@ registries:
- `branch` (optional): Branch name to use (defaults to `main`)
- `tag` (optional): Tag name to pin to a specific version
- `commit` (optional): Commit SHA to pin to a specific commit
- `path` (required): Path to the registry file within the repository
- `path` (optional): Path to the registry file within the repository (defaults
to `registry.json`)
- `auth.username` (optional): Username for Git authentication
- `auth.passwordFile` (optional): Path to a file containing the Git password or
token

:::tip

Expand Down Expand Up @@ -221,12 +231,11 @@ Server standalone (without the operator).

:::

:::note

Currently, only resources in the same namespace as the Registry Server are
discovered.

:::
By default, the Registry server discovers resources in all namespaces
(cluster-wide). You can restrict discovery to specific namespaces using the
`THV_REGISTRY_WATCH_NAMESPACE` environment variable. See
[Workload discovery](./deployment.mdx#workload-discovery) for configuration
details and RBAC requirements.

```yaml title="config-kubernetes.yaml"
registries:
Expand Down Expand Up @@ -258,7 +267,7 @@ apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
name: my-mcp-server
namespace: toolhive-system # Must match Registry Server namespace
namespace: toolhive-system
annotations:
toolhive.stacklok.dev/registry-export: 'true'
toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server'
Expand All @@ -279,6 +288,7 @@ spec:
| `toolhive.stacklok.dev/registry-export` | Yes | Must be `"true"` to include in registry |
| `toolhive.stacklok.dev/registry-url` | Yes | The external endpoint URL for this server |
| `toolhive.stacklok.dev/registry-description` | Yes | Description text displayed in registry listings |
| `toolhive.stacklok.dev/tools` | No | JSON array of tool name strings (e.g., `["get_weather","get_forecast"]`) |
| `toolhive.stacklok.dev/tool-definitions` | No | JSON array of tool definitions with MCP tool metadata (name, description, schema) |

**Tool definitions format:**
Expand All @@ -303,7 +313,7 @@ URL within the publisher-provided metadata:
```json
{
"_meta": {
"publisher-provided": {
"io.modelcontextprotocol.registry/publisher-provided": {
"io.github.stacklok": {
"https://mcp.example.com/servers/my-mcp-server": {
"tool_definitions": [...]
Expand Down Expand Up @@ -410,9 +420,9 @@ information on configuring each mode.

## Database configuration

The server optionally supports PostgreSQL database connectivity for storing
registry state and metadata. See the [Database configuration](./database.mdx)
guide for detailed information.
The server requires a PostgreSQL database for storing registry state and
metadata. See the [Database configuration](./database.mdx) guide for detailed
information.

## Telemetry configuration

Expand All @@ -425,4 +435,4 @@ distributed tracing and metrics collection. See the
- [Configure authentication](./authentication.mdx) for secure access
- [Configure telemetry](./telemetry-metrics.mdx) for metrics and tracing
- [Deploy the server](./deployment.mdx) with your configuration
- [Configure database storage](./database.mdx) for production use
- [Configure database storage](./database.mdx)
69 changes: 54 additions & 15 deletions docs/toolhive/guides-registry/database.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ description:
Registry server
---

The Registry server optionally supports PostgreSQL database connectivity for
storing registry state and metadata. This enables persistence across restarts
and provides a foundation for advanced features.
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.

## Configuration

Expand All @@ -23,24 +23,27 @@ database:
maxOpenConns: 25
maxIdleConns: 5
connMaxLifetime: '5m'
maxMetaSize: 65536
```

### Configuration fields

| Field | Type | Required | Default | Description |
| ----------------- | ------ | -------- | --------- | -------------------------------------------------------------------------- |
| `host` | string | Yes | - | Database server hostname or IP address |
| `port` | int | Yes | - | Database server port |
| `user` | string | Yes | - | Database username for normal operations |
| `migrationUser` | string | No | `user` | Database username for running migrations (should have elevated privileges) |
| `database` | string | Yes | - | Database name |
| `sslMode` | string | No | `require` | SSL mode (`disable`, `require`, `verify-ca`, `verify-full`) |
| `maxOpenConns` | int | No | `25` | Maximum number of open connections to the database |
| `maxIdleConns` | int | No | `5` | Maximum number of idle connections in the pool |
| `connMaxLifetime` | string | No | `5m` | Maximum lifetime of a connection (e.g., "1h", "30m") |
| Field | Type | Required | Default | Description |
| ----------------- | ------ | -------- | --------- | -------------------------------------------------------------------------------------------------- |
| `host` | string | Yes | - | Database server hostname or IP address |
| `port` | int | Yes | - | Database server port |
| `user` | string | Yes | - | Database username for normal operations |
| `migrationUser` | string | No | `user` | Database username for running migrations (should have elevated privileges) |
| `database` | string | Yes | - | Database name |
| `sslMode` | string | No | `require` | SSL mode (`disable`, `require`, `verify-ca`, `verify-full`) |
| `maxOpenConns` | int | No | `25` | Maximum number of open connections to the database |
| `maxIdleConns` | int | No | `5` | Maximum number of idle connections in the pool |
| `connMaxLifetime` | string | No | `5m` | Maximum lifetime of a connection (e.g., "1h", "30m") |
| `maxMetaSize` | int | No | `65536` | Maximum allowed size in bytes for publisher-provided metadata extensions |
| `dynamicAuth` | object | No | - | Dynamic authentication configuration (see [Dynamic authentication](#dynamic-authentication) below) |

\* Password configuration is required but has multiple sources (see Password
Security below)
Security and Dynamic authentication below)

## Password security

Expand Down Expand Up @@ -119,6 +122,42 @@ for more details.
You can find more details about user creation and initial configuration in this
[test file](https://github.com/stacklok/toolhive-registry-server/blob/301ccf4e3ad13daad28be7b669d8e5fca337ec14/cmd/thv-registry-api/app/serve_test.go#L56-L103).

## Dynamic authentication

As an alternative to pgpass files, the server supports dynamic credential
generation for cloud-hosted databases.

### AWS RDS IAM authentication

When running on AWS, you can authenticate to RDS using IAM credentials instead
of static passwords. The server generates short-lived authentication tokens
using the IAM role attached to the workload.

```yaml title="config-aws-rds.yaml"
database:
host: my-database.123456789.us-east-1.rds.amazonaws.com
port: 5432
user: my_app_user
database: registry
sslMode: require
dynamicAuth:
awsRdsIam:
region: us-east-1
```

**Configuration options:**

- `dynamicAuth.awsRdsIam.region` (required): The AWS region of the RDS instance.
Set to `detect` to automatically determine the region from the EC2 instance
metadata service (IMDS).

:::note

Dynamic authentication replaces pgpass files. The server generates
authentication tokens automatically before each connection.

:::

## Database migrations

The server uses database migrations to manage schema changes. Migrations run
Expand Down
Loading