Skip to main content
Credible’s MCP tools use the Credible Context Engine to ground any LLM or agent in governed data definitions. When you ask a question, the get_context tool parses your 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 LLM gets ranked entity matches and Malloy syntax guidance, so it can construct accurate queries without hallucinating field names or misunderstanding your data structure.
This page covers the consumption MCP server used by LLMs, workspace chat, and custom agents. The Credible-Modeling MCP server used by coding agents for building models is a separate, auto-configured server — see Local Development.
This page covers: Connecting a personal chat client like Claude or ChatGPT? See Connect your Agent. Connecting an IDE or CLI coding agent like Cursor, Copilot, or Claude Code? See Local Development.

​
The MCP Server

Use your organization’s MCP server URL: https://<your-org>.mcp.credibledata.com/mcp The URL can optionally be workspace-scoped by appending /workspace/{workspace_name}. This restricts analysis to only the packages available in a specific workspace, rather than searching across all environments:
  • Environment-scoped (default): https://<your-org>.mcp.credibledata.com/mcp
  • Workspace-scoped: https://<your-org>.mcp.credibledata.com/mcp/workspace/{workspace_name}
You can copy the full workspace-scoped URL from your workspace settings page.

​
Connecting Custom Agents

Custom agents and services — anything running server-to-server, where an OAuth sign-in flow isn’t available — authenticate with a group-scoped API key. Create one by following Create an API Key, then come back here to connect. All requests to the MCP server must include the API key in the Authorization header:

​
Testing with curl

You can verify your connection with curl before integrating with your agent framework. First, initialize a connection to validate your API key:
Then list the available tools:
This should return a list including get_context and execute_query.

​
Tool Reference

However it connects — OAuth or API key — your LLM or agent has access to two 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) annotations declared in your model — the richer your documentation, the better the matches. This is the core retrieval tool powering the 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) 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?”)
  • environment_name (optional): Environment name to search within. Only use if known from context.
  • package_name (optional): Package name to narrow search scope. Requires environment_name.
  • model_uri (optional): Path to a specific .malloy model file. Requires environment_name and package_name.
  • source_name (optional): Specific source within a model. Requires environment_name, package_name, and model_uri.
Parameter Dependencies: environment_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:

​
execute_query

Executes Malloy queries against published data models and returns JSON results. Parameters:
  • environment_name (required): Environment 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

​
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. Have custom authentication requirements? Contact us to discuss your use case.