Skip to main content
Credible’s MCP tools don’t just give your agent access to data—they use the Intelligent Context Engine to find the right data for each query. When a user asks a natural language question, our retrieval system searches your model’s metadata (documentation tags, indexed field values) and uses embedding models to find semantically relevant fields—not just exact matches. Your agent gets suggested queries, related entities, 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 the Admin UI at yourorg.admin.credibledata.com:
  1. Open Admin Controls (in the bottom left)
  2. Click Create Group
  3. Name your group (e.g., ai_agents_group)
Create Group in Admin UI

​
2. Grant Project Access

Navigate to the project you want this group to access:
  1. Click Share (in the top right)
  2. Select Group from the dropdown
  3. Add your group in the “Add people or groups” section
  4. Verify the group appears under “Groups with access”
Share Project with Group

​
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 suggestAnalysis and executeQuery.

​
Available MCP Tools

Once connected, your agent has access to two tools:
  • suggestAnalysis - Searches your semantic models based on natural language and returns suggested queries plus related data entities
  • executeQuery - 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.