Skip to main content
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_values) 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:
  1. Click Users & Groups in the bottom left of the sidebar
  2. Switch to the Groups tab
  3. Click + Create Group and name your group (e.g., ai_agents_group)

​
2. Grant Project Access

Navigate to the project you want this group to access:
  1. Click Permissions on the project page
  2. Add your group and select the appropriate role
  3. 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

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_values) 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.