diff --git a/product/enterprise-offering/secret-references.mdx b/product/enterprise-offering/secret-references.mdx
index 109c46fe..d54d1030 100644
--- a/product/enterprise-offering/secret-references.mdx
+++ b/product/enterprise-offering/secret-references.mdx
@@ -239,6 +239,7 @@ Each entry in the `secret_mappings` array:
 | `target_field` | string | Yes | The field on the entity that should be populated from the secret reference. Must be unique within the array. |
 | `secret_reference_id` | string | Yes | UUID or slug of the secret reference to resolve. Must belong to the same organisation and be accessible by the workspace. |
 | `secret_key` | string \| null | No | Override the `secret_key` defined on the secret reference. Use to pick a specific key from a multi-value secret. |
+| `value_format` | string \| null | No | Format of the secret value. Either `json` or `string`. Use `json` when the secret value is a JSON object that should be parsed. |
 
 ### From the Control Panel
 
@@ -261,12 +262,46 @@ If you're storing provider API keys in your vault, map your secrets in LLM Integ
 
 ### Valid `target_field` Values
 
+<Tabs>
+  <Tab title="LLM Integrations">
 **Integrations** (`POST /v1/integrations`, `PUT /v1/integrations/:integrationId`)
 
 | target_field | Description |
 |-------------|-------------|
 | `key` | The provider API key. When mapped, the `key` body field can be omitted. |
 | `configurations.<field>` | Any provider-specific configuration field (e.g. `configurations.aws_secret_access_key`, `configurations.azure_entra_client_secret`). |
+  </Tab>
+  <Tab title="MCP Integrations">
+**MCP Integrations** (`POST /v1/mcp-integrations`, `PUT /v1/mcp-integrations/:mcpIntegrationId`)
+
+| target_field | Description |
+|-------------|-------------|
+| `configurations.<field>` | Any MCP server configuration field (e.g. `configurations.oauth_metadata`, `configurations.api_key`). |
+
+MCP integrations support the same secret mapping functionality as LLM integrations. This is particularly useful for:
+- **OAuth credentials**: Store OAuth client secrets, tokens, and metadata in your vault
+- **API keys**: Reference API keys for MCP servers that use header-based authentication
+- **Complex configurations**: Use `value_format: "json"` for nested configuration objects like OAuth metadata
+
+**Example: MCP Integration with OAuth metadata from vault**
+
+```json
+{
+  "name": "GitHub MCP",
+  "slug": "github-mcp",
+  "server_url": "https://api.githubcopilot.com/mcp",
+  "auth_type": "oauth",
+  "secret_mappings": [
+    {
+      "target_field": "configurations.oauth_metadata",
+      "secret_reference_id": "my-github-oauth",
+      "value_format": "json"
+    }
+  ]
+}
+```
+  </Tab>
+</Tabs>
 
 
 ### Example
@@ -282,11 +317,35 @@ If you're storing provider API keys in your vault, map your secrets in LLM Integ
       "target_field": "configurations.aws_secret_access_key",
       "secret_reference_id": "aws-credentials-ref",
       "secret_key": "secret_access_key"
+    },
+    {
+      "target_field": "configurations.oauth_metadata",
+      "secret_reference_id": "my-github-oauth",
+      "value_format": "json"
+    }
+  ]
+}
+```
+
+#### Using `value_format: json`
+
+When your secret value is a JSON object (not a plain string), use `value_format: "json"` to have Portkey parse the value as JSON before injecting it into the configuration.
+
+```json
+{
+  "secret_mappings": [
+    {
+      "secret_key": "oauth_metadata",
+      "target_field": "configurations.oauth_metadata",
+      "value_format": "json",
+      "secret_reference_id": "my-github-oauth"
     }
   ]
 }
 ```
 
+This is useful for complex configuration objects like OAuth metadata that contain multiple nested fields.
+
 ### Validation Rules
 
 - `secret_mappings` must be an array (if provided).