Skip to main content
Technical reference for the Credible Data consumption MCP server, available at https://<org>.mcp.credibledata.com/mcp.
This page documents the consumption MCP server used by LLMs, workspace chat, and custom agents. The Credible-Modeling MCP server used by the Cursor agent for building models is a separate, auto-configured server — see Set Up Your IDE.

​
Core Tools

​
get_context

Parses a natural language question into semantic phrases, then matches each phrase to data entities in your published semantic models. Matches are grounded in the #(doc) descriptions and #(index_values) annotations declared in your model — the richer your documentation, the better the matches. This is the core retrieval tool powering Credible’s Credible Context Engine. How it works:
  1. Phrase extraction — An LLM parses your input into semantic phrases (e.g., “top selling brands by month” becomes phrases like “top selling”, “brands”, “by month”)
  2. Entity matching — Each phrase is matched against your model’s indexed metadata using embedding-based semantic search. This searches #(doc) descriptions, field names, and #(index_values) dimensional values. Matching is semantic, not exact — for example, “soccer games” can match a program titled “World Cup Finals” via indexed values and a genre of “Sports” via doc tags
  3. Ranked results — Returns matched entities (dimensions, measures, views, columns) grouped by phrase, sorted by match score
Credible Context Engine matching phrases to semantic model entities Parameters:
  • natural_language_query (required): The user’s question in natural language (e.g., “What were our top-selling products last year?”)
  • project_name (optional): Project name to search within. Only use if known from context.
  • package_name (optional): Package name to narrow search scope. Requires project_name.
  • model_uri (optional): Path to a specific .malloy model file. Requires project_name and package_name.
  • source_name (optional): Specific source within a model. Requires project_name, package_name, and model_uri.
Parameter Dependencies: project_name → package_name → model_uri → source_name Scope Strategy: Start broad when uncertain, narrow as you discover structure. If results are insufficient, widen scope by removing parameters from right to left. Response:
  • sources: Array of matched sources, each containing:
    • phrases: Matched phrases from your input, each with:
      • phrase: The extracted phrase text
      • phrase_description: Extended description of the phrase
      • overall_score: Match confidence score
      • entities: Matched data entities (dimensions, measures, views, columns) with name, field_type, data_type, description, score, match_reason, and values (for dimensions with indexed values)
  • next_steps: Instructions for writing Malloy queries using the returned entities
  • malloy_documentation: Malloy syntax reference and common error patterns
Example Request: 
curl -X POST "https://your-org.mcp.credibledata.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_context",
      "arguments": {
        "natural_language_query": "What are the top 10 products by sales?",
        "project_name": "your-project"
      }
    }
  }'

​
execute_query

Executes Malloy queries against published data models and returns JSON results. Parameters:
  • project_name (required): Project containing the model
  • package_name (required): Package containing the model
  • model_uri (required): Path to the .malloy model file
  • query (optional)*: Custom Malloy query code. Do NOT provide source_name when using this.
  • query_name (optional)*: Name of predefined query/view to execute
  • source_name (optional)*: Source name. Required when using query_name, omit when using custom query.
  • version_id (optional): Specific package version to query against
*Execution Patterns: Use exactly ONE of:
  1. Custom query: Provide query parameter only
  2. Predefined query: Provide both query_name and source_name
Response: Returns query results as JSON with data, totalRows, executionTime, and metadata

​
Workspace Scoping

The MCP server URL can optionally be workspace-scoped by appending /workspace to the URL. This restricts analysis to only the packages available in a specific workspace, rather than searching across all projects.
  • Project-scoped (default): https://<org>.mcp.credibledata.com/mcp
  • Workspace-scoped: https://<org>.mcp.credibledata.com/mcp/workspace

​
Authentication

The MCP server supports two authentication methods:
  • OAuth 2.0: For connecting AI assistants like Claude Desktop or ChatGPT. See LLMs and MCP Tools.
  • API Key: For building custom agents with server-to-server communication. Pass as Authorization: ApiKey YOUR_API_KEY header. See Custom AI Agents.
Configure your MCP client with your organization’s endpoint: https://<org>.mcp.credibledata.com/mcp

​
Error Handling

The server returns standard MCP error responses for invalid requests, authentication failures, and query execution errors. Refer to the MCP specification for error code details.