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

Configure your AI assistant

For ​ValidMind Cloud production, use:

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.

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 YOUR_API_KEY and YOUR_API_SECRET with your ValidMind credentials.⁴

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

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 YOUR_API_KEY and YOUR_API_SECRET with your ValidMind credentials.⁵

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 correct MCP URL 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.