diff --git a/site/about/glossary/mcp/_mcp-server.qmd b/site/about/glossary/mcp/_mcp-server.qmd new file mode 100644 index 000000000..d75893093 --- /dev/null +++ b/site/about/glossary/mcp/_mcp-server.qmd @@ -0,0 +1,6 @@ + + +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. diff --git a/site/about/glossary/mcp/_mcp-tool.qmd b/site/about/glossary/mcp/_mcp-tool.qmd new file mode 100644 index 000000000..739c6cd6e --- /dev/null +++ b/site/about/glossary/mcp/_mcp-tool.qmd @@ -0,0 +1,6 @@ + + +MCP tool +: An operation exposed by an MCP server that AI assistants can invoke to perform actions, such as querying models or updating artifacts. diff --git a/site/about/glossary/mcp/_mcp.qmd b/site/about/glossary/mcp/_mcp.qmd new file mode 100644 index 000000000..0dca829df --- /dev/null +++ b/site/about/glossary/mcp/_mcp.qmd @@ -0,0 +1,6 @@ + + +MCP (Model Context Protocol) +: An open standard that enables AI assistants to connect to external data sources and tools through a unified protocol, allowing natural language interactions with structured systems. diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index b5d7d6dcd..fd3b30412 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -42,9 +42,10 @@ website: contents: - guide/integrations/manage-secrets.qmd - guide/integrations/configure-connections.qmd - - guide/integrations/configure-analytics-exports.qmd - guide/integrations/implement-custom-integrations.qmd - guide/integrations/link-external-models.qmd + - guide/mcp/connect-ai-assistants-via-mcp.qmd + - guide/integrations/configure-analytics-exports.qmd - guide/integrations/integrations-examples.qmd - text: "---" - text: "Workflows" diff --git a/site/guide/integrations/managing-integrations.qmd b/site/guide/integrations/managing-integrations.qmd index 2e63178ca..db6c7c1e8 100644 --- a/site/guide/integrations/managing-integrations.qmd +++ b/site/guide/integrations/managing-integrations.qmd @@ -33,6 +33,7 @@ graph TD E[Public REST API] F[Testing & documentation] G[Service integration] + H[AI assistants] A <--> B A <--> C @@ -40,6 +41,7 @@ graph TD A <--> E A <--> F A <--> G + A <--> H ``` @@ -194,6 +196,29 @@ Link to tickets in external systems and keep them synchronized. Attach tickets t :::: +--- + +### AI assistants + +Connect AI assistants to {{< var vm.product >}} using the Model Context Protocol (MCP). Query and manage your model inventory through natural language conversations.[^7] + +**Supported** + +:::: {.flex .flex-wrap .justify-around} + +::: {.w-33-ns} +- Claude Desktop +::: + +::: {.w-33-ns} +- Cursor IDE +::: + +::: {.w-33-ns} +  +::: + +:::: ## Key concepts @@ -233,4 +258,5 @@ Link to tickets in external systems and keep them synchronized. Attach tickets t [^3]: [Introduction to workflows](/guide/workflows/introduction-to-workflows.qmd) [^4]: [Public REST API](/reference/validmind-rest-api-vm.qmd) [^5]: [Testing & documentation](/developer/validmind-library.qmd) -[^6]: [Configure analytics exports](/guide/integrations/configure-analytics-exports.qmd) \ No newline at end of file +[^6]: [Configure analytics exports](/guide/integrations/configure-analytics-exports.qmd) +[^7]: [Connect AI assistants](/guide/mcp/connect-ai-assistants-via-mcp.qmd) \ No newline at end of file diff --git a/site/guide/mcp/connect-ai-assistants-via-mcp.qmd b/site/guide/mcp/connect-ai-assistants-via-mcp.qmd new file mode 100644 index 000000000..a1d8f9ecb --- /dev/null +++ b/site/guide/mcp/connect-ai-assistants-via-mcp.qmd @@ -0,0 +1,198 @@ +--- +# 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: "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 model inventory through natural language, providing seamless access to models, artifacts, templates, and custom fields. + + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You have your API key and secret.[^1] +- [x] You have a compatible AI assistant installed: + - Cursor IDE[^2] + - Claude Code[^3] + +::: + +## Key concepts + +{{< include /about/glossary/mcp/_mcp.qmd >}} + +{{< include /about/glossary/mcp/_mcp-server.qmd >}} + +{{< include /about/glossary/mcp/_mcp-tool.qmd >}} + +### How does {{< var vm.product >}} MCP work? + +```{mermaid} +graph LR + subgraph ai [AI assistants] + Claude[Claude Code] + Cursor[Cursor IDE] + end + + subgraph mcp [MCP layer] + MCPServer[ValidMind MCP Server] + end + + subgraph vm [ValidMind Platform] + Models[Models] + Artifacts[Artifacts] + Templates[Templates] + CustomFields[Custom fields] + end + + Claude --> MCPServer + Cursor --> MCPServer + MCPServer --> Models + MCPServer --> Artifacts + MCPServer --> Templates + MCPServer --> CustomFields +``` + +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 >}}. + +### What can I do with {{< var vm.product >}} MCP? + +The MCP server exposes tools for working with your model inventory: + +:::: {.flex .flex-wrap .justify-around} + +::: {.w-50-ns .pr3} + +**Model and artifact operations** + +- List and get models +- List and get artifacts +- Filter by risk level, deployment region, or ownership + +**Custom field operations** + +- List custom fields for models and artifacts +- Update custom field values + +::: + +::: {.w-50-ns .pl3} + +**Template operations** + +- List available templates +- Get template details +- Validate templates +- Duplicate and update templates + +::: + +:::: + +**Example queries you can ask:** + +- "Show me all models that are high risk" +- "Find all the models I am an owner for" +- "List my validation artifacts" +- "What templates are available for credit risk models?" + +## Configure your AI assistant + +::: {.panel-tabset} + +### Cursor IDE + +1. In Cursor, open **Settings** > **Cursor Settings** and navigate to the **MCP** section. + +2. Click **Add new global MCP server** to open your `~/.cursor/mcp.json` file. + +3. Add the {{< var vm.product >}} MCP server configuration: + + ```json + { + "mcpServers": { + "validmind": { + "url": "https://api.prod.validmind.ai/mcp", + "headers": { + "x-api-key": "YOUR_API_KEY", + "x-api-secret": "YOUR_API_SECRET" + } + } + } + } + ``` + +4. Replace `YOUR_API_KEY` and `YOUR_API_SECRET` with your ValidMind credentials.[^1] + +5. Save the file and reload Cursor with the **Command/Ctrl + Shift + P** > **Developer: Reload Window** shortcut. + +6. Return to **Cursor Settings > MCP** and verify that the ValidMind server appears. If it shows as disabled, click the toggle to enable it. + +7. Try asking Cursor questions like: + + - "What models do I own?" + - "Show me all tier 1 models" + - "Register a new model called Customer Churn" + +### Claude Code + +1. In Claude Code, add the {{< var vm.product >}} MCP server (this updates your `~/.claude.json` file): + + ```bash + claude mcp add --transport http validmind https://api.prod.validmind.ai/mcp \ + --header "x-api-key:YOUR_API_KEY" \ + --header "x-api-secret:YOUR_API_SECRET" + ``` + +2. Replace `YOUR_API_KEY` and `YOUR_API_SECRET` with your ValidMind credentials.[^1] + +3. Verify the connection: + + ```bash + claude mcp list + ``` + + You should see `validmind` with status `✓ Connected`. + +4. Start Claude Code and try asking questions like: + + - "What models do I own?" + - "Show me all tier 1 models" + - "Register a new model called Customer Churn" + +::: + +## Troubleshooting + +::: {.panel-tabset} + +### Connection refused or timeout errors + +- Verify your network can reach `api.prod.validmind.ai`. +- Check if your organization uses a firewall or proxy that blocks MCP connections. +- Ensure you are using the correct MCP URL for your environment. + +### Authentication errors (401 or 403) + +- Confirm your API key and secret are correct. +- Check that your API credentials have not expired. +- Verify your account has the necessary permissions to access the requested resources. + +### MCP server not appearing in Cursor + +- Ensure the configuration file is saved at `~/.cursor/mcp.json`. +- Validate the JSON syntax in your configuration file. +- 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. + +::: + + + +[^1]: [Get your API key and secret](/reference/validmind-rest-api-vm.qmd#get-your-api-key-and-secret) +[^2]: [Cursor](https://cursor.com) +[^3]: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)