From a7b8134e8b863b6303a87bdd5f72517499e2cb22 Mon Sep 17 00:00:00 2001 From: lujunsan Date: Wed, 4 Feb 2026 01:39:37 +0100 Subject: [PATCH 1/4] Document tool definitions annotation for registry Signed-off-by: lujunsan --- .../guides-registry/configuration.mdx | 38 ++++++++++++++++--- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index c412baa0..5a7c0be6 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -240,7 +240,7 @@ of workloads. The types being watched are The Registry server will receive events when a resource among those listed above is annotated with the following annotations: -```yaml {7-10} +```yaml {7-11} apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: @@ -251,15 +251,41 @@ metadata: toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server' toolhive.stacklok.dev/registry-description: | Production MCP server for code analysis + toolhive.stacklok.dev/tool-definitions: + '[{"name":"analyze_code","description":"Analyze code for potential + issues","inputSchema":{"type":"object","properties":{"file":{"type":"string","description":"Path + to the file to + analyze"},"rules":{"type":"array","items":{"type":"string"},"description":"List + of rule IDs to check"}},"required":["file"]}}]' spec: # ... MCP server spec ``` -| Annotation | Required | Description | -| -------------------------------------------- | -------- | ----------------------------------------- | -| `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 | Override the description in registry | +| Annotation | Required | Description | +| -------------------------------------------- | -------- | --------------------------------------------------------------------------------- | +| `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/tool-definitions` | No | JSON array of tool definitions with MCP tool metadata (name, description, schema) | + +**Tool definitions format:** + +The `tool-definitions` annotation accepts a JSON array containing tool metadata +that follows the MCP specification. Each tool definition can include: + +- `name` (required): Tool identifier +- `description`: Human-readable description of what the tool does +- `inputSchema`: JSON Schema describing the tool's input parameters +- `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 +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. + +Tool definitions appear in the Registry API response at: +`_meta.publisher-provided.io.github.stacklok..tool_definitions` This feature requires the Registry server to be granted access to those resources via a Service Account, check the details in the From 66fd5ba86e32a8f753642a3abee95463a5d5c6f6 Mon Sep 17 00:00:00 2001 From: lujunsan Date: Wed, 4 Feb 2026 01:51:05 +0100 Subject: [PATCH 2/4] Address Copilot feedback on tool definitions docs Signed-off-by: lujunsan --- docs/toolhive/guides-registry/configuration.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 5a7c0be6..6903c7d2 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -284,8 +284,12 @@ 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. -Tool definitions appear in the Registry API response at: -`_meta.publisher-provided.io.github.stacklok..tool_definitions` +Tool definitions appear in the Registry API response at a key of the form: +`_meta.publisher-provided.io.github.stacklok..tool_definitions`, +where `` is the exact value of the `registry-url` annotation for +that server. For example, if the annotation is +`https://mcp.example.com/servers/my-mcp-server`, the field appears as +`_meta.publisher-provided.io.github.stacklok.https://mcp.example.com/servers/my-mcp-server.tool_definitions`. This feature requires the Registry server to be granted access to those resources via a Service Account, check the details in the From d11a852deef3d7cca50367f302fb7e7dcbe813a2 Mon Sep 17 00:00:00 2001 From: lujunsan Date: Wed, 4 Feb 2026 02:01:44 +0100 Subject: [PATCH 3/4] Fix formatting Signed-off-by: lujunsan --- docs/toolhive/guides-registry/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 6903c7d2..f26a11fd 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -240,7 +240,7 @@ of workloads. The types being watched are The Registry server will receive events when a resource among those listed above is annotated with the following annotations: -```yaml {7-11} +```yaml {7-16} apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: From d76565bc6cc48b5c64af993d1a2e7a51d7492635 Mon Sep 17 00:00:00 2001 From: lujunsan Date: Wed, 4 Feb 2026 02:09:35 +0100 Subject: [PATCH 4/4] Reformat tool definitions explanation for easier interpretation Signed-off-by: lujunsan --- .../guides-registry/configuration.mdx | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index f26a11fd..237f9a66 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -284,12 +284,25 @@ 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. -Tool definitions appear in the Registry API response at a key of the form: -`_meta.publisher-provided.io.github.stacklok..tool_definitions`, -where `` is the exact value of the `registry-url` annotation for -that server. For example, if the annotation is -`https://mcp.example.com/servers/my-mcp-server`, the field appears as -`_meta.publisher-provided.io.github.stacklok.https://mcp.example.com/servers/my-mcp-server.tool_definitions`. +Tool definitions appear in the Registry API response under the server's registry +URL within the publisher-provided metadata: + +```json +{ + "_meta": { + "publisher-provided": { + "io.github.stacklok": { + "https://mcp.example.com/servers/my-mcp-server": { + "tool_definitions": [...] + } + } + } + } +} +``` + +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 resources via a Service Account, check the details in the