Clarify the docs around _meta publisher extensions (#695)

docs/reference/server-json/generic-server-json.md

@@ -14,6 +14,22 @@ The schema contains all field definitions, validation rules, examples, and detai
 
 The official registry has some more restrictions on top of this. See the [official registry requirements](./official-registry-requirements.md) for details.
 
+## Extension Metadata with `_meta`
+
+The optional `_meta` field allows publishers to include custom metadata alongside their server definitions using reverse DNS namespacing.
+
+```jsonc
+{
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      // Your custom metadata here
+    }
+  }
+}
+```
+
+When publishing to the official registry, custom metadata must be placed under the key `io.modelcontextprotocol.registry/publisher-provided`. See the [official registry requirements](./official-registry-requirements.md) for detailed restrictions and examples.
+
 ## Examples
 
 <!-- As a heads up, these are used as part of tests/integration/main.go -->

docs/reference/server-json/official-registry-requirements.md

@@ -43,6 +43,87 @@ Only trusted public registries are supported. Private registries and alternative
 
 ## `_meta` Namespace Restrictions
 
-The `_meta` field is restricted to the `publisher` key only during publishing. This `_meta.publisher` extension is currently limited to 4KB.
+The `_meta` field in `server.json` allows publishers to include custom metadata alongside their server definitions.
 
-Registry metadata is added automatically and cannot be overridden.
+### Publisher-Provided Metadata
+
+When publishing to the official registry, **only data under the specific key `io.modelcontextprotocol.registry/publisher-provided` will be preserved**. Any other keys in the `_meta` object are silently dropped during publishing and will not be stored or returned by the registry.
+
+**Example:**
+
+```jsonc
+{
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "tool": "ci-publisher",
+      "version": "1.0.0",
+      "custom_data": "your data here"
+    },
+    "some.other.key": {
+      // This will be dropped and not preserved
+    }
+  }
+}
+```
+
+**Size limit:** The publisher-provided extension is limited to 4KB (4096 bytes) of JSON. If the marshaled JSON exceeds this limit, publishing will fail with an error indicating the actual size.
+
+### Registry API Metadata vs server.json Metadata
+
+The `_meta` field in `server.json` is **different** from the `_meta` field returned in registry API responses:
+
+- **In `server.json`**: The `_meta` field contains publisher-provided custom metadata under `io.modelcontextprotocol.registry/publisher-provided`
+- **In API responses**: The `_meta` field is returned as a separate property at the response level (not inside `server.json`) and contains registry-managed metadata like:
+  - `status`: Server lifecycle status (active, deprecated, deleted)
+  - `publishedAt`: When the server was first published
+  - `updatedAt`: When the server was last updated
+  - `isLatest`: Whether this is the latest version
+
+**Example: What you publish (server.json)**
+
+```jsonc
+{
+  "name": "io.github.example/my-server",
+  "version": "1.0.0",
+  "description": "My MCP server",
+  // ... other fields ...
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "tool": "ci-publisher",
+      "version": "2.0.0"
+    }
+  }
+}
+```
+
+**Example: What the registry API returns**
+
+```jsonc
+{
+  "server": {
+    "name": "io.github.example/my-server",
+    "version": "1.0.0",
+    "description": "My MCP server",
+    // ... other fields ...
+    "_meta": {
+      "io.modelcontextprotocol.registry/publisher-provided": {
+        "tool": "ci-publisher",
+        "version": "2.0.0"
+      }
+    }
+  },
+  "_meta": {
+    // Registry-managed metadata at response level
+    "status": "active",
+    "publishedAt": "2024-01-15T10:30:00Z",
+    "updatedAt": "2024-01-15T10:30:00Z",
+    "isLatest": true
+  }
+}
+```
+
+Notice how the registry API response has **two** `_meta` fields:
+1. Inside the `server` object: Your publisher-provided metadata (preserved from server.json)
+2. At the response level: Registry-managed metadata (automatically added by the registry)
+
+Registry-managed metadata cannot be set or overridden by publishers. See the [API documentation](../api/generic-registry-api.md) for the complete response structure.