From d251b71caee4b2bc49d25ef87747f087dbb16e05 Mon Sep 17 00:00:00 2001 From: Emma Van Der Heide Date: Thu, 30 Jul 2026 16:28:03 -0400 Subject: [PATCH 1/2] docs: align MCP guide with current inventory tool surface [sc-17040] Expand capabilities, fix filter claims, reconcile supported clients, and document limitations against the shipped ValidMind MCP server. Co-authored-by: Cursor --- site/about/glossary/mcp/_mcp-server.qmd | 2 +- site/about/glossary/mcp/_mcp-tool.qmd | 2 +- site/faq/faq-integrations.qmd | 2 +- site/guide/chatbot-capabilities.qmd | 2 +- .../integrations/managing-integrations.qmd | 2 +- .../mcp/connect-ai-assistants-via-mcp.qmd | 66 ++++++++++++++----- 6 files changed, 53 insertions(+), 23 deletions(-) diff --git a/site/about/glossary/mcp/_mcp-server.qmd b/site/about/glossary/mcp/_mcp-server.qmd index d758930933..0e829708c5 100644 --- a/site/about/glossary/mcp/_mcp-server.qmd +++ b/site/about/glossary/mcp/_mcp-server.qmd @@ -3,4 +3,4 @@ Refer to the LICENSE file in the root of this repository for details. SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial --> MCP server -: A service that exposes tools and resources to AI assistants via the MCP protocol. The {{< var vm.product >}} MCP server provides access to model inventory operations. +: A service that exposes tools and resources to AI assistants via the MCP protocol. The {{< var vm.product >}} MCP server provides access to inventory records, artifacts, templates, custom fields, and supporting schemas or lookups. diff --git a/site/about/glossary/mcp/_mcp-tool.qmd b/site/about/glossary/mcp/_mcp-tool.qmd index 739c6cd6e5..b13c8f61f3 100644 --- a/site/about/glossary/mcp/_mcp-tool.qmd +++ b/site/about/glossary/mcp/_mcp-tool.qmd @@ -3,4 +3,4 @@ Refer to the LICENSE file in the root of this repository for details. SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial --> MCP tool -: An operation exposed by an MCP server that AI assistants can invoke to perform actions, such as querying models or updating artifacts. +: An operation exposed by an MCP server that AI assistants can invoke to perform actions, such as listing records, creating findings, or updating templates. diff --git a/site/faq/faq-integrations.qmd b/site/faq/faq-integrations.qmd index d409a7f831..c42f4eb901 100644 --- a/site/faq/faq-integrations.qmd +++ b/site/faq/faq-integrations.qmd @@ -66,7 +66,7 @@ Supported connections include:[^10] - **Analytics and reporting** — Microsoft Power BI, plus scheduled data exports to cloud storage for use with external BI and reporting tools.[^18] - **Workflow automation** — HTTP requests from {{< var vm.product >}} to external services and webhooks from external systems into {{< var vm.product >}}.[^19] - **Testing and documentation** — {{< var validmind.developer >}} integrations with development platforms, including MLflow and AWS SageMaker.[^20] -- **AI assistants** — Claude Desktop and Cursor IDE through the Model Context Protocol (MCP).[^21] +- **AI assistants** — Claude Code and Cursor IDE through the Model Context Protocol (MCP).[^21] If your system isn't supported out-of-the-box, you can build a custom integration that implements the {{< var vm.product >}} reference API.[^22] diff --git a/site/guide/chatbot-capabilities.qmd b/site/guide/chatbot-capabilities.qmd index 70f663da79..8b6ee83401 100644 --- a/site/guide/chatbot-capabilities.qmd +++ b/site/guide/chatbot-capabilities.qmd @@ -47,7 +47,7 @@ Keep these limitations in mind when using the assistant: |---------|------------------|-----------------| | Access method | Floating chat window in platform | AI assistants (Cursor, Claude Code) | | Primary use | Product help and guidance | Inventory management | -| Data access | Documentation + your current context | Your records (models), artifacts (findings), templates | +| Data access | Documentation + your current context | Your records, artifacts (findings), templates, custom fields, and related schemas | | Actions | Read-only guidance | Create, read, update operations | The in-app assistant (described on this page) is focused on helping you use the platform. For programmatic access to your inventory, refer to [Connect AI assistants via MCP](/guide/mcp/connect-ai-assistants-via-mcp.qmd). diff --git a/site/guide/integrations/managing-integrations.qmd b/site/guide/integrations/managing-integrations.qmd index 741d4a8caf..f6d9afa21e 100644 --- a/site/guide/integrations/managing-integrations.qmd +++ b/site/guide/integrations/managing-integrations.qmd @@ -259,7 +259,7 @@ Connect AI assistants to {{< var vm.product >}} using the Model Context Protocol :::: {.flex .flex-wrap .justify-around} ::: {.w-33-ns} -- Claude Desktop +- Claude Code ::: ::: {.w-33-ns} diff --git a/site/guide/mcp/connect-ai-assistants-via-mcp.qmd b/site/guide/mcp/connect-ai-assistants-via-mcp.qmd index 36c22559a5..a6f291babb 100644 --- a/site/guide/mcp/connect-ai-assistants-via-mcp.qmd +++ b/site/guide/mcp/connect-ai-assistants-via-mcp.qmd @@ -6,7 +6,7 @@ title: "Connect AI assistants via MCP" date: last-modified --- -The {{< var vm.product >}} MCP (Model Context Protocol) server enables AI assistants to query and manage your inventory through natural language, providing seamless access to records (models), artifacts (findings), templates, and custom fields. +The {{< var vm.product >}} MCP (Model Context Protocol) server enables AI assistants to query and manage your inventory through natural language. Assistants can work with records (models and other inventory types), artifacts (findings), templates, custom fields, and the supporting lookups needed to create and update those objects safely. ## Key concepts @@ -30,21 +30,23 @@ graph LR end subgraph vm [ValidMind Platform] - Models[Models] + Records[Records] Artifacts[Artifacts] Templates[Templates] - CustomFields[Custom fields] + Fields[Custom fields] + Lookups[Schemas and lookups] end Claude --> MCPServer Cursor --> MCPServer - MCPServer --> Models + MCPServer --> Records MCPServer --> Artifacts MCPServer --> Templates - MCPServer --> CustomFields + MCPServer --> Fields + MCPServer --> Lookups ``` -Your AI assistant sends natural language queries through the MCP protocol. The {{< var vm.product >}} MCP server translates these into API calls, authenticates using your API key, and returns data from the {{< var validmind.platform >}}. +Your AI assistant sends natural language queries through the MCP protocol. The {{< var vm.product >}} MCP server translates these into API calls, authenticates using your API credentials, and returns data from the {{< var validmind.platform >}}. ### What can I do with {{< var vm.product >}} MCP? @@ -52,18 +54,23 @@ The MCP server exposes tools for working with your {{< var vm.product >}} invent ::: {.panel-tabset} -#### Record and artifact operations +#### Records and artifacts -- List and get records (models) -- List and get artifacts (findings) -- Filter by risk level, deployment region, or ownership +- List, get, and summarize records across inventory record types +- Create and update records +- List, get, and summarize artifacts (currently findings) +- Create and update findings linked to a record +- Filter records by search text, tiering, status, use case, business unit, owners, developers, validators, and related flags +- Filter artifacts by severity, status, assignee, risk area, due date, and related criteria -#### Custom field operations +#### Schemas and lookups -- List custom fields for records and artifacts -- Update custom field values +- Discover primary record types, use cases, business units, groups, model stages, and organization users +- Read core field schemas and artifact types +- Discover custom field schemas for records and artifacts +- Read and update custom field values on records and artifacts -#### Template operations +#### Templates - List available templates - Get template details @@ -73,13 +80,23 @@ The MCP server exposes tools for working with your {{< var vm.product >}} invent ::: ::: {.callout title="Example queries you can ask"} -- "Show me all model-type records that are high risk" +- "Show me all tier 1 model-type records" - "Find all the records I am an owner for" -- "List my validation artifacts" +- "Summarize findings by severity for this model" +- "Register a new model-type record called Customer Churn" +- "Create a finding on that record and assign it to me" - "What templates are available for credit risk models?" ::: +::: {.callout-note} +## Current limitations + +- The MCP server covers inventory records, artifacts, templates, custom fields, and supporting schemas or lookups. It does not write documentation content or run ValidMind Library tests. +- Artifact operations currently support the `finding` artifact type only. +- Requests may be rate limited depending on your environment. +::: + ::: {.attn} ## Prerequisites @@ -94,6 +111,14 @@ The MCP server exposes tools for working with your {{< var vm.product >}} invent ## Configure your AI assistant +For {{< var vm.product >}} Cloud production, use: + +```text +https://api.prod.validmind.ai/mcp +``` + +If your organization uses a different cloud host or a private deployment, use the MCP URL provided for your environment. + ::: {.panel-tabset} ### Cursor IDE @@ -164,9 +189,9 @@ The MCP server exposes tools for working with your {{< var vm.product >}} invent ### Connection refused or timeout errors -- Verify your network can reach `api.prod.validmind.ai`. +- Verify your network can reach `api.prod.validmind.ai` (or your environment's MCP host). - Check if your organization uses a firewall or proxy that blocks MCP connections. -- Ensure you are using the correct MCP URL for your environment. +- Ensure you are using the correct MCP URL for your environment. For {{< var vm.product >}} Cloud production, use `https://api.prod.validmind.ai/mcp`. ### Authentication errors (401 or 403) @@ -181,6 +206,11 @@ The MCP server exposes tools for working with your {{< var vm.product >}} invent - Reload Cursor after making configuration changes. - Check **Cursor Settings > MCP** to verify the server appears and is enabled. You may need to manually toggle the server on after adding it to the configuration. +### Rate limiting or unexpected denials + +- If requests fail intermittently under heavy use, wait briefly and retry. +- Confirm your credentials still have access to the records, artifacts, or templates you are requesting. + ::: From e3a2ed362d1c717943f63c2d1c64a81b9e02fc6b Mon Sep 17 00:00:00 2001 From: Emma Van Der Heide Date: Thu, 30 Jul 2026 16:59:39 -0400 Subject: [PATCH 2/2] docs: surface in-app assistant page under Integrations [sc-17040] Rename Chatbot capabilities, enable search, and add it beside the MCP guide in the Guides sidebar. Co-authored-by: Cursor --- AGENTS.md | 2 +- site/guide/_sidebar.yaml | 1 + site/guide/chatbot-capabilities.qmd | 3 +-- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ea895c86c1..c31b2cdeab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ This page explains: If you are an AI agent embedded in ValidMind, your capabilities are documented here: -**[Chatbot capabilities](https://docs.validmind.ai/guide/chatbot-capabilities.html)** +**[ValidMind in-app assistant](https://docs.validmind.ai/guide/chatbot-capabilities.html)** This page describes what the assistant can and cannot do, including context-aware features and current limitations. diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index 98a9483bd2..f4117d20dc 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -51,6 +51,7 @@ website: - guide/integrations/implement-custom-integrations.qmd - guide/integrations/link-external-records.qmd - guide/mcp/connect-ai-assistants-via-mcp.qmd + - guide/chatbot-capabilities.qmd - guide/integrations/configure-data-exports.qmd - file: guide/integrations/integrations-examples.qmd contents: diff --git a/site/guide/chatbot-capabilities.qmd b/site/guide/chatbot-capabilities.qmd index 8b6ee83401..e49d7ef793 100644 --- a/site/guide/chatbot-capabilities.qmd +++ b/site/guide/chatbot-capabilities.qmd @@ -2,9 +2,8 @@ # Copyright © 2023-2026 ValidMind Inc. All rights reserved. # Refer to the LICENSE file in the root of this repository for details. # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -title: "Chatbot capabilities" +title: "ValidMind in-app assistant" date: last-modified -search: false --- The {{< var vm.product >}} in-app assistant helps you navigate the platform and find answers to product questions. This page describes what the assistant can and cannot do.