MCP Tools

MCP (Model Context Protocol) is the open standard agents use to connect to tools — and Credible's MCP tools are the same get_context and execute_query every Credible surface runs, available to any agent you build. They use the Credible AI Analytics 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.

On this page:

• The MCP server — the endpoint and how to scope it
• Connecting custom agents — your own applications, authenticated with a Bearer token or a group-scoped API key
• Tool reference — get_context and execute_query parameters and responses

Connecting a personal chat client like Claude or ChatGPT? See Connect your Agent. Connecting an IDE or CLI coding agent like Copilot, Claude Code, or Gemini CLI? See Connect your Coding Agent.

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:

• Organization-scoped (default): https://<your-org>.mcp.credibledata.com/mcp — searches every published package you can access, across all environments
• 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

The MCP server accepts the same two authentication schemes as the REST APIs:

• Bearer token — Acts as the signed-in user, with their permissions. This is what the OAuth flow in MCP clients produces, and you can use it directly for interactive testing or scripts run by a person:

Authorization: Bearer <access-token>

• API key — Acts as a group. For custom agents and services — anything running server-to-server, where an OAuth sign-in flow isn't available — create a group-scoped key by following Create an API Key:

Authorization: ApiKey your-api-key

Testing with curl

You can verify your connection with curl before integrating with your agent framework. The examples use an API key; substitute Authorization: Bearer <access-token> to test as yourself. First, initialize a connection to validate your credentials:

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

Then list the available 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 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 AI Analytics 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

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:

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?",
        "environment_name": "your-environment"
      }
    }
  }'

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.