> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools
> The Credible consumption MCP server — connecting custom agents and the get_context / execute_query tool reference
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 Analytics Engine](/how-to/analyzing/overview) 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 **modeling MCP tools** coding agents use to build models — the same open tools Malloy Publisher provides — are served separately and configured automatically; see the [VS Code Extension](/how-to/developers/vscode-extension#modeling-mcp-tools).
On this page:
* **[The MCP server](#the-mcp-server)** — the endpoint and how to scope it
* **[Connecting custom agents](#connecting-custom-agents)** — your own applications, authenticated with a Bearer token or a group-scoped API key
* **[Tool reference](#tool-reference)** — `get_context` and `execute_query` parameters and responses
Connecting a personal chat client like Claude or ChatGPT? See [Connect your Agent](/how-to/analyzing/connect-your-llm). Connecting an IDE or CLI coding agent like Copilot, Claude Code, or Gemini CLI? See [Connect your Coding Agent](/how-to/developers/connect-coding-agent).
## The MCP Server
Use your organization's MCP server URL: `https://.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://.mcp.credibledata.com/mcp`
* **Workspace-scoped**: `https://.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](/how-to/integrating/apis#authentication) 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
```
* **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](/how-to/integrating/apis#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 ` to test as yourself. First, initialize a connection to validate your credentials:
```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
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://.mcp.credibledata.com/mcp | jq
```
Then list the available tools:
```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
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://.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 Analytics Engine](/how-to/analyzing/overview#how-it-works).
**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:**
```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
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](mailto:support@credibledata.com) to discuss your use case.