docs: security model for vault mcp server

content/vault/v1.20.x/content/docs/mcp-server/security-model.mdx

@@ -1,15 +1,101 @@
 ---
 page_title: Security model for Vault MCP server  
 description: |-
- Learn how to understand security implications while working with the Vault MCP Server.
+ Learn about Vault's MCP Server security model to identify potential security threats and follow our recommendations for using the Vault MCP Server securely.
 ---
 
 # Security model for Vault MCP server
 
-This document explains the security model for the Vault Model Context Protocol (MCP) server when operating the server locally.
+## Purpose of this document
+
+This document explains the security model for the Vault Model Context Protocol (MCP) server when operating the server locally using the STDIO or streamable HTTP transport.
 Understanding this model helps you safely integrate local AI agents with Vault tooling.
 This ensures the following outcomes, even in local environments:
 
 - Tool execution is safe and controlled
 - Sensitive operations are protected from accidental misuse or injection
 - LLM behavior is constrained and auditable prior to application.
+
+## Important concepts
+
+### Model Context Protocol (MCP)
+
+MCP is a protocol allowing language models (or agents) to call tools programmatically through structured and standardized definitions.
+
+### MCP Host
+
+An AI application or environment in which AI-driven tasks are performed that operates the MCP client. (e.g. Claude Desktop).
+
+### MCP Client
+
+The MCP Client handles discovery and communication between the MCP Host and the MCP Server by translating model prompts into executable actions.
+
+### MCP Server
+
+A service which gets called by the MCP Client to execute various tools, resources and prompts. It provides a server or tool manifest for allowing dynamic discovery of available capabilities.
+
+### MCP Tool
+
+A server-defined executable function or operation (e.g. "list", "write", "delete") with defined inputs and outputs callable by clients.
+
+### MCP Transport
+
+The underlying communication of how messages are sent and received via JSON-RPC 2.0. Stdio allows direct tool invocation via standard input/output pipe. Streamable HTTP exposes a local server (e.g., on 127.0.0.1:port) to receive and respond to MCP tool calls.
+
+## Threat model
+
+~> **Legal Note** Your use of a third party MCP Client/LLM is subject solely to the terms of use for such MCP/LLM, and IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP Clients/LLMs, and may not be able to provide support to resolve issues which are caused by the third party tools. 
+
+### Hallucination
+
+AI hallucinations, or the generation of false information, stem from insufficient training data, flawed model assumptions, and biased datasets. They pose serious risks in critical applications where accuracy is vital for correct diagnoses and sound decisions. We recommend users to always validate the output of the LLM model prior to applying any changes in their environment.
+
+### Prompt injection
+
+Improper validation or sanitization of user input can allow attackers to inject malicious instructions that the MCP Server will execute. This can lead to code execution, Server Side Request Forgery (SSRF), and various other security breaches.
+
+### Tool Poisoning
+
+Tool poisoning occurs when the MCP Server inadvertently executes hidden instructions within comprehensive tool descriptions, enabling attackers to instigate unwanted or damaging outcomes
+
+### Rug Pull Attack
+
+In case a remotely accessible MCP Server changes its available tools and descriptions after being deployed, this enables malicious behavior that wasn't present when the tool was initially approved.
+
+### Tool Shadowing
+
+When multiple MCP servers are connected, a malicious one can override tools from a trusted one, leading to potential security breaches.
+
+## Threat Model Exclusions
+
+The following are not part of the threat model for the Vault MCP Server:
+
+### Foundational model
+
+Concerns related to the underlying AI models, training data, and inherent vulnerabilities.
+
+## Recommendations for securely using the Vault MCP Server
+
+### Ensuring local-only server access
+
+We recommend running the MCP Server locally (127.0.0.1) through the STDIO or HTTP Streamable transport protocol to limit the exposure of your Vault environment to the public. The default transport is set to STDIO. Users deciding to host the service remotely should add additional security controls at the application and network level.
+
+### Enabling CORS
+
+By default, the supported CORS mode is strict and the allowed origins are empty meaning that all cross-origin requests will be blocked unless the server is explicitly configured to allow them. Users should cautiously edit the allowed origins to include the MCP Client and Vault server endpoints.
+
+### Protect authentication to Vault
+
+We recommend not disabling the `VAULT_SKIP_VERIFY` option to keep comminication with your Vault environment encrypted. We also recommend to not use a root or shared `VAULT_TOKEN`, the Vault token used should be created by the end-user running the MCP server and have limited permissions associated to it.
+
+### Rate limiting
+
+We recommend setting up the global and per session rate limiting to prevent overloading the MCP server or dependent resources such as the Vault instance through excessive requests.
+
+### Securing in-transit communication
+
+In case you want to make your MCP Server accessible remotely, we enforce configuring a valid TLS certificate to protect in-transit communication of your data.
+
+### Disabling privileged operations
+
+The `ENABLE_VAULT_OPERATIONS` option is used to enable or disable tools that performs privileged opperations. We recommend setting it to false if you don't want to allow the MCP Server to create, edit or remove secrets in Vault.