Connecting to the Validatar MCP Server

Validatar exposes a Model Context Protocol (MCP) server that lets AI assistants and development tools work directly with your Validatar instance. Through MCP you can browse your catalog, create and run tests, run scripts, and manage metadata from an AI tool such as Claude Code, GitHub Copilot, Cursor or OpenAI Codex.

Tip: The Validatar Agent Kits set all of this up for you, tool by tool, and add skills, worked examples and helper scripts so the agent builds tests the way an experienced Validatar engineer would.

Prerequisites

Before connecting to the Validatar MCP server:

• Your Validatar instance must be running a version that includes MCP support.
• You need a Validatar user with permissions for the work you intend to do. The MCP server acts as that user.
• You need the address of your Validatar instance (for example https://your-instance.cloud.validatar.com).
• Your AI tool must support MCP servers over HTTP (Streamable HTTP) and let you set a custom request header.

How MCP Works with Validatar

The Model Context Protocol is an open standard that lets AI assistants call tools on external systems. The Validatar MCP server:

• Runs over HTTP with stateless transport
• Authenticates each request with a Validatar user token of type MCP
• Exposes read and write tools for your catalog, tests, projects and metadata
• Records every write as an AI Action that can be reviewed and reverted

Connection Configuration

Endpoint

The MCP server is available at:

{your_validatar_instance_url}/core/mcp

The /core prefix is required in the MCP endpoint URL. It is not part of the address you use for links in the browser.

Authentication

The MCP server authenticates with a Validatar user token of type MCP. This is a dedicated token, not your password, a session cookie or an API-type token.

To create an MCP token:

1. Log in to your Validatar instance.
2. Open your User Profile settings.
3. Under User Tokens, create a new token and set the type to MCP.
4. Copy the generated token value.

The token is sent in the x-val-api-token header:

x-val-api-token: <your-token>

Treat the token like a password. Keep it in an environment variable, and use your tool's environment-variable syntax in its configuration so the token is never written into a file that might be committed.

Client Configuration Examples

The examples below read the instance address from VALIDATAR_URL (no trailing slash) and the token from VALIDATAR_MCP_TOKEN. Set both as environment variables for your user account, then restart the tool.

Claude Code

Add a .mcp.json file at the root of your project:

{
  "mcpServers": {
    "validatar": {
      "type": "http",
      "url": "${VALIDATAR_URL}/core/mcp",
      "headers": {
        "x-val-api-token": "${VALIDATAR_MCP_TOKEN}"
      }
    }
  }
}

Claude Code expands ${...} from the environment when it starts, so the file holds no secret and can be shared with your team. The first time you start Claude Code in the project, approve the validatar server when asked. Type /mcp to check that it is connected.

To write the same .mcp.json from the command line (macOS, Linux, or Git Bash on Windows):

claude mcp add --transport http --scope project validatar https://your-instance.cloud.validatar.com/core/mcp --header 'x-val-api-token: ${VALIDATAR_MCP_TOKEN}'

The single quotes keep ${VALIDATAR_MCP_TOKEN} as typed, so .mcp.json stores the variable name, not the token. To make the server available in every project instead, use --scope user; Claude Code then stores it in your user configuration (~/.claude.json) rather than in the project.

Note: Claude Code does not read MCP servers from .claude/settings.json. Use .mcp.json or claude mcp add.

Full setup, with the skills and helper scripts: Validatar Agent Kit for Claude Code.

Cursor

In .cursor/mcp.json (this project) or ~/.cursor/mcp.json (every project):

{
  "mcpServers": {
    "validatar": {
      "url": "${env:VALIDATAR_URL}/core/mcp",
      "headers": {
        "x-val-api-token": "${env:VALIDATAR_MCP_TOKEN}"
      }
    }
  }
}

Open Settings > MCP to check that validatar is enabled. Full setup: Validatar Agent Kit for Cursor.

Other tools

Cortex Code in Snowsight and Databricks Genie Code accept only OAuth or bearer-token MCP servers, so they cannot connect to the Validatar MCP server today.

Generic MCP Client

Any MCP client that supports HTTP transport and custom headers can connect:

Verifying Your Connection

Once configured, verify the connection by asking your AI assistant to run a read-only operation:

1. Ask the assistant to list your projects or describe a known data source.
2. If the connection works, the assistant returns results from your Validatar instance.
3. If authentication fails, you receive an error. Check that the token is an MCP-type token and that the instance address is right.

Tool Access Control

Validatar administrators can control which MCP tools are available to specific users through token-based access control. If a tool is unavailable to you, contact your Validatar administrator to verify your permissions.

Tools are divided into two categories:

• Read-only tools: browse catalog objects, list tests, search documentation
• Write tools: create tests, execute scripts, update metadata, manage folders and projects

See MCP Tools Reference for the complete list of tools.

AI Action Tracking and Revert

Every write operation performed through MCP is logged as an AI Action. This provides:

• A full audit trail of changes made through AI assistants
• The ability to revert any AI-initiated change with the revert_action tool
• Visibility into what was changed, when, and by which user

When a write tool runs successfully, the response includes a revert_action_key that can be used to undo the change.

Troubleshooting

Next Steps

• Set up a Validatar Agent Kit for your AI tool.
• Review the MCP Tools Reference to see which operations are available.
• Try browsing your catalog by asking the assistant to describe a data source or list the tables in a schema.