Connect AI assistants via MCP

The ​ValidMind 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

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.

MCP server

A service that exposes tools and resources to AI assistants via the MCP protocol. The ​ValidMind MCP server provides access to inventory records, artifacts, templates, custom fields, and supporting schemas or lookups.

MCP tool

An operation exposed by an MCP server that AI assistants can invoke to perform actions, such as listing records, creating findings, or updating templates.

How does ​ValidMind MCP work?

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]
        Records[Records]
        Artifacts[Artifacts]
        Templates[Templates]
        Fields[Custom fields]
        Lookups[Schemas and lookups]
    end
    
    Claude --> MCPServer
    Cursor --> MCPServer
    MCPServer --> Records
    MCPServer --> Artifacts
    MCPServer --> Templates
    MCPServer --> Fields
    MCPServer --> Lookups

Your AI assistant sends natural language queries through the MCP protocol. The ​ValidMind MCP server translates these into API calls, authenticates using your API credentials, and returns data from the ValidMind Platform.

What can I do with ​ValidMind MCP?

The MCP server exposes tools for working with your ​ValidMind inventory:

Records and artifacts

• 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

Schemas and lookups

• 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

Templates

• List available templates
• Get template details
• Validate templates
• Duplicate and update templates

NoneExample queries you can ask

• “Show me all tier 1 model-type records”
• “Find all the records I am an owner for”
• “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?”

NoteCurrent 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.

Prerequisites

• You are logged in to ValidMind.
• You have your API key and secret.¹
• You have a compatible AI assistant installed:
  • Cursor IDE²
  • Claude Code³

¹ Get your API key and secret

² Cursor

³ Claude Code

Get your MCP connection details

Each record’s Getting Started page includes a Connect to MCP section with the MCP URL and headers for your environment, plus a Claude Code configuration snippet prefilled with your API credentials:

1. In the left sidebar, click Inventory.

2. Select the type of {Record} you want to open by clicking on {Record} Inventory.⁴

3. Select any record by clicking on it or find a record by applying a filter or searching for it.⁵

4. In the left sidebar that appears for your record, click Getting Started.

5. Scroll to the Connect to MCP section at the bottom of the page and note the:

   • MCP URL: The address your AI assistant connects to, for example https://api.prod.validmind.ai/mcp for ​ValidMind Cloud production.
   • Headers: X-API-KEY with your API key and X-API-SECRET with your API secret. The page masks your secret as API_SECRET.

⁴ Manage inventory record types

⁵ Working with the inventory

The MCP URL and your credentials are the same on every record’s Getting Started page, so you can open any record. Your AI assistant can then work with all the records you have access to.

NoneThe Connect to MCP section uses your API key and secret.

• If you have no API credentials yet or your API key has expired, the page shows an alert and the copy button is disabled. Generate or regenerate your credentials in your profile settings, then return to the page.⁶
• If your organization only allows OIDC connectivity for the ValidMind Library, the Connect to MCP section does not appear. Ask your administrator how to connect to the MCP server in your environment.

⁶ Get your API key and secret

Configure your AI assistant

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 ​ValidMind MCP server configuration:

   {
     "mcpServers": {
       "validmind": {
         "url": "https://api.prod.validmind.ai/mcp",
         "headers": {
           "x-api-key": "YOUR_API_KEY",
           "x-api-secret": "YOUR_API_SECRET"
         }
       }
     }
   }

4. Replace the URL with the MCP URL from the Getting Started page, and replace YOUR_API_KEY and YOUR_API_SECRET with your API key and secret.⁷

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 records do I own?”
   • “Show me all tier 1 model-type records”
   • “Register a new model-type record called Customer Churn”

⁷ Get your API key and secret

Claude Code

Use the snippet from Getting Started

1. On the Getting Started page, under Connect to MCP > Claude Code, click Copy snippet to clipboard.

   The copied snippet includes your API key and secret.

2. Paste the snippet into the .mcp.json file at the root of your project and save it.

   If the file already lists other MCP servers, add the validmind entry inside your existing mcpServers object.

3. Start Claude Code in your project and approve the validmind server when prompted. Claude Code asks before it uses a server from a project’s .mcp.json file.

4. Verify the connection:

   claude mcp list

   You should see validmind with status ✓ Connected.

Add the server from the command line

1. In Claude Code, add the ​ValidMind MCP server (this updates your ~/.claude.json file):

   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 the URL with the MCP URL from the Getting Started page, and replace YOUR_API_KEY and YOUR_API_SECRET with your API key and secret.⁸

3. Verify the connection:

   claude mcp list

   You should see validmind with status ✓ Connected.

4. Start Claude Code and try asking questions like:

   • “What records do I own?”
   • “Show me all tier 1 model-type records”
   • “Register a new model-type record called Customer Churn”

⁸ Get your API key and secret

Troubleshooting

Connection refused or timeout errors

• 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 MCP URL shown on the Getting Started page for your environment. For ​ValidMind Cloud production, use https://api.prod.validmind.ai/mcp.

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.

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.