Connecting to Claravine via the Model Context Protocol (MCP)

This article explains how to connect an AI assistant — such as Claude, ChatGPT, or Goose — to your Claravine instance using the Model Context Protocol (MCP).

What is the Model Context Protocol (MCP)?

Think of MCP as a USB-C port for AI applications. Just as USB-C provides a standardized way to connect devices to your phone or laptop, MCP provides a standardized way to connect AI assistants to external systems and data sources.

MCP is an open standard designed to solve a simple problem: AI assistants need a reliable way to access your data, tools, and workflows. Before MCP, every AI integration had to be custom-built. With MCP, AI applications can connect to platforms like Claravine using a single, universal protocol.

By connecting an AI assistant to Claravine through MCP, your team can submit data, validate against governance rules, and explore templates through natural-language conversations rather than navigating the application interface manually.

How Claravine + MCP works

Once connected, your AI assistant can interact directly with your Claravine instance. You describe what you want to accomplish in plain language, and the AI carries out the request on your behalf.

Key benefits

• Faster workflows. Submit and validate data conversationally, without navigating forms or memorizing field names.
• Fewer errors. Data is validated against your template's governance rules before submission, catching missing required fields or invalid values early.
• Self-service access. Non-technical team members can work with Claravine data using an AI assistant rather than learning technical interfaces.
• Faster onboarding. New users can ask the AI to explain template structures and field requirements instead of searching through documentation.

Example prompts

• "Find my Social Media Campaign template and show me what fields I need to fill out."
• "Submit this file to the Campaigns template in Claravine. Validate the values first."
• "Validate this data against my Ads template."
• "What values are allowed in the Region field of our Campaign Template?"

Authentication options

The Claravine MCP server supports two authentication methods:

1. API Key — Connect using a generated key and secret.
2. OAuth — Sign in with your Claravine credentials through Auth0.

Choose the method that fits your setup. Each method uses a different connection URL — your client will not connect unless you use the URL that matches your chosen method.

Does the Claravine MCP server support SSO?

Yes — through the OAuth authentication option. OAuth sign-in is handled by Auth0, Claravine's identity provider. If your Claravine account is configured to authenticate users via SSO through Auth0, signing in to the MCP server with OAuth will follow that same SSO flow.
 

If you are unsure whether your account is configured for SSO, contact your Claravine administrator or Claravine Support.

Option 1: Setting up API Key authentication

Use this method if you prefer connecting with a generated API key and secret rather than signing in interactively.

Steps

1. In Claravine, navigate to your Account Settings and open the API Keys section.
2. Click Create API Key.
3. Copy the generated key and secret. Store them securely — you will need both when configuring your MCP client.
4. In your MCP client, set the transport type to Streamable HTTP and use the API Key connection URL below.
5. Add the required headers to your client configuration, replacing the placeholder values with your actual key and secret.

Connection details

Required headers

Note: API Key authentication requires public API keys to be enabled on your account. If you do not see the API Keys section in your account settings, contact your Claravine administrator or Claravine Support.

Option 2: Setting up OAuth authentication

Use this method to authenticate with your existing Claravine credentials (including SSO, if your account is configured for it).

Steps

1. In Claravine, go to Account → Details.
2. If your account does not already have an Auth0 Tenant Organization ID configured, click Configure account on new Auth0 Tenant and complete the setup.
3. In your MCP client, set the transport type to Streamable HTTP and use the OAuth connection URL below.
4. When you connect, your client will prompt you to sign in with your Claravine credentials through Auth0.

Connection details

Note: OAuth does not require an API key.

Choosing an MCP client

The Claravine MCP server works with any MCP-compatible client. Since it’s a custom connector, you won’t see it listed in Anthropic’s or OpenAI’s official MCP/app directories.

To get connected, you’ll just need to follow a few setup steps. We’ve included links in the Notes section of the table below that take you to the official Anthropic and OpenAI guides, which walk through how to add a custom connector.
 

Note: Several MCP clients let you control how tools are executed. For example, you can configure specific Claravine MCP tools to require confirmation before they run—so if you want to avoid accidental actions (like an unintended submission), you can ensure the client always asks for approval first.
 

Recommended options:

If you use a different MCP-compatible client, the same connection URLs and authentication options apply.

Available actions

Once connected, your AI assistant can perform the following actions in Claravine.

Template management

Submission management

Submission statuses you may see: Pending, Complete, Error, Paused, Awaiting Approval, Approved, Resumed, Rejected, Deleted, Removal, Awaiting Classification, Unknown.

List management

Tip: Use the Validate rows action before submitting data. If any row fails validation during a real submission, the entire submission moves to a draft or pending state and no integrations will run until the issues are resolved.

Limits and processing notes

• Maximum 1,000 rows per submission and per validation request.
• When you create a submission, the MCP server polls for status for up to 30 seconds. If the submission is still pending after that, use the Check submission status action to continue monitoring.
• The Get submission data action only works for submissions that have completed processing. Confirm the status is Complete before retrieving data.
• Field names sent to the MCP server must match the template's field names exactly.

Troubleshooting

If your MCP client is not connecting or actions are failing, check the following:

• Before taking action in the MCP server, confirm the connector is live between the server and the Claravine platform. 
• Verify your API key and secret are entered correctly with no extra spaces.
• Confirm your client is configured with the correct transport type (Streamable HTTP) and the URL that matches your authentication method.
• Ensure all required headers are properly set in your client configuration.
• Check that template UUIDs and submission UUIDs are accurate when referencing specific records.
• For OAuth issues, confirm your account has an Auth0 Tenant Organization ID configured.

If you continue to experience issues, contact Claravine Support.