Custom AI Agents (MCP) - Credible Data

Credible’s MCP tools use the Credible Context Engine to ground your agent in governed data definitions. When a user asks a question, the get_context tool parses the input into semantic phrases and matches each phrase to data entities (dimensions, measures, views) in your semantic model — searching against the #(doc) descriptions and #(index) annotations declared in your model. Your agent gets ranked entity matches and Malloy syntax guidance, so it can construct accurate queries without hallucinating field names or misunderstanding your data structure.

Looking to connect via OAuth? See LLMs and MCP Tools for connecting third-party AI tools like Claude Desktop or ChatGPT.

Authentication Setup

1. Create a Group

Navigate to yourorg.app.credibledata.com:

Click Users & Groups in the bottom left of the sidebar
Switch to the Groups tab
Click + Create Group and name your group (e.g., ai_agents_group)

2. Grant Environment Access

Navigate to the environment you want this group to access:

Click Permissions on the environment page
Add your group and select the appropriate role
Verify the group appears in the permissions list

3. Create an API Key (CLI)

Install the Credible CLI, authenticate, and generate an API key for your group:

# Install the CLI globally
npm install -g @credibledata/cred-cli

# Login to your organization
cred login <your-org>

# Create a group access token
cred add group-access-token <group-name> <token-name>

The final command will output an API key that you’ll use in your MCP client configuration.

Security: Store the API key securely in your application’s credential storage or environment variables. Future API calls will act with the permissions of your assigned group. You can modify group permissions at any time without regenerating the token.

Connecting Your Agent

Using an MCP Client

Use your organization’s MCP server URL: https://<your-org>.mcp.credibledata.com/mcp To restrict analysis to a specific workspace, use the workspace-scoped URL instead: https://<your-org>.mcp.credibledata.com/mcp/workspace/{workspace_name}. You can copy the full workspace-scoped URL from your workspace settings page. Here’s an example using Mastra’s MCP client:

import dotenv from 'dotenv';
dotenv.config();

import { MCPClient } from '@mastra/mcp';

/**
 * Configure the MCP client with a remote server
 * The server is accessed via HTTP and authenticated with an API key
 */
export const mcp = new MCPClient({
  id: 'remote-mcp-client',
  servers: {
    credible: {
      // Remote MCP server URL (replace <your-org> with your organization name)
      url: new URL('https://<your-org>.mcp.credibledata.com/mcp'),

      // Force HTTP transport (not SSE)
      transport: 'http',

      // Configure request options including authentication headers
      requestInit: {
        headers: {
          // Pass API key in Authorization header with ApiKey prefix
          Authorization: `ApiKey ${process.env.MCP_API_KEY}`,
        },
      },
    },
  },

  // Global timeout for all MCP operations (in milliseconds)
  timeout: 60000,
});

// Connect to the server
await mcp.connect();

// Use the client to get available tools
const tools = await mcp.getTools();

Configuration Notes:

transport: 'http' - Explicitly sets HTTP transport mode (required for remote connections)
id - Unique identifier for this MCP client instance
url - Replace <your-org> with your organization name in the URL
Environment Variables - Store your API key in environment variables for security (recommended for production)
timeout - Global timeout for all MCP operations in milliseconds

Authentication Header

All requests to the MCP server must include the API key in the Authorization header:

Authorization: ApiKey your-api-key

Troubleshooting

Testing Your Connection with curl

You can verify your MCP connection using curl before integrating with your agent framework. These examples assume you have your API key stored in an environment variable:

1. Test Connection (Initialize)

This verifies your authentication and establishes a connection:

source .env && curl -X POST \
  -H "Authorization: ApiKey ${MCP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }' \
  https://<your-org>.mcp.credibledata.com/mcp | jq

A successful response indicates your API key is valid and the server is accessible.

2. List Available Tools

Once connected, verify you can access the MCP tools:

source .env && curl -X POST \
  -H "Authorization: ApiKey ${MCP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }' \
  https://<your-org>.mcp.credibledata.com/mcp | jq

This should return a list of available tools including get_context and execute_query.

Available MCP Tools

Once connected, your agent has access to two tools:

get_context — Parses the user’s question into phrases, matches each phrase to data entities (dimensions, measures, views) in your semantic model, and returns ranked matches grounded in your model’s #(doc) and #(index) annotations
execute_query — Executes Malloy queries against your semantic models and returns JSON results

For complete technical details on parameters and responses, see the MCP Reference. Have custom authentication requirements? Contact us to discuss your use case.

​Authentication Setup

​1. Create a Group

​2. Grant Environment Access

​3. Create an API Key (CLI)

​Connecting Your Agent

​Using an MCP Client

​Authentication Header

​Troubleshooting

​Testing Your Connection with curl

​1. Test Connection (Initialize)

​2. List Available Tools

​Available MCP Tools

Authentication Setup

1. Create a Group

2. Grant Environment Access

3. Create an API Key (CLI)

Connecting Your Agent

Using an MCP Client

Authentication Header

Troubleshooting

Testing Your Connection with curl

1. Test Connection (Initialize)

2. List Available Tools

Available MCP Tools