--- title: "Connecting to the Validatar MCP Server" slug: "connecting-to-the-validatar-mcp-server" updated: 2026-11-06T15:08:22Z published: 2026-11-06T15:08:22Z canonical: "docs.validatar.com/connecting-to-the-validatar-mcp-server" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.validatar.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/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: ``` 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](/docs/validatar-agent-kit-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](/docs/validatar-agent-kit-cursor). #### Other tools | Tool | Where the server is configured | Setup article | | --- | --- | --- | | OpenAI Codex | `~/.codex/config.toml` or the project's `.codex/config.toml`, with `env_http_headers` | [Validatar Agent Kit for OpenAI Codex](/docs/validatar-agent-kit-codex) | | GitHub Copilot | `.vscode/mcp.json` (VS Code), `.mcp.json` (Copilot CLI), repository settings (cloud agent) | [Validatar Agent Kit for GitHub Copilot](/docs/validatar-agent-kit-github-copilot) | | Snowflake Cortex Code (CLI, Desktop) | `~/.snowflake/cortex/mcp.json` | [Validatar Agent Kit for Snowflake Cortex Code](/docs/validatar-agent-kit-cortex-code) | | Google Antigravity, Gemini CLI | `~/.gemini/config/mcp_config.json`, `.gemini/settings.json` | [Validatar Agent Kit for Google Antigravity](/docs/validatar-agent-kit-antigravity) | | Kiro | `.kiro/settings/mcp.json` | [Validatar Agent Kit for Kiro](/docs/validatar-agent-kit-kiro) | | Devin | `.devin/mcp_config.json` | [Validatar Agent Kit for Devin](/docs/validatar-agent-kit-devin) | 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: | Setting | Value | | --- | --- | | **Transport** | HTTP (Streamable HTTP, stateless) | | **URL** | `{instance_url}/core/mcp` | | **Authentication** | `x-val-api-token` header with your MCP-type user token | --- ## 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](/docs/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 | Symptom | Cause | Resolution | | --- | --- | --- | | Connection refused or 404 | Instance address wrong, or MCP not available on your version | Check that the URL ends in `/core/mcp` and that your Validatar version supports MCP | | 401 Unauthorized | Invalid, expired or wrong type of token | Use a user token of type **MCP** (not API). Create a new one if needed | | The header shows as `${VALIDATAR_MCP_TOKEN}` in errors | The tool started before the environment variable was set | Set the variable, then fully restart the tool | | Tool not found | Tool access restricted for your account | Ask your administrator to check token-level tool permissions | | Timeout on requests | Network issues or long-running operations | Check connectivity; for scripts, consider increasing timeout parameters | --- ## Next Steps - Set up a [Validatar Agent Kit](/docs/validatar-agent-kits) for your AI tool. - Review the [MCP Tools Reference](/docs/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.