MCP Server and Tools

Credible's MCP server endpoints, how a custom agent authenticates with a bearer token or group API key, and the parameters of get_context, execute_query, get_skill, search_malloy_docs and search_credible_docs

Credible runs a remote MCP (Model Context Protocol) server that any agent can use to query published data models. Developers connecting their own agent or service need its endpoints, an authentication scheme, and the tools each endpoint exposes. To connect an off-the-shelf client, see Chat Clients or Coding Agents.

An agent uses the tools in a loop: get_context to find the sources and fields a question needs, then execute_query to run a Malloy query written from them. How It Works explains the retrieval behind it.

The MCP Server

The server speaks MCP over Streamable HTTP. There is one global endpoint and three narrower ones:

EndpointURLReaches
Globalhttps://mcp.credibledata.com/global/Every organization, workspace and package the caller can read
Organizationhttps://<your-org>.mcp.credibledata.com/mcpPackages the caller can read in one organization
Workspacehttps://<your-org>.mcp.credibledata.com/mcp/workspace/<workspace>The packages in one shared workspace
Packagehttps://<your-org>.mcp.credibledata.com/mcp/package/<environment>/<package>One package

The narrower endpoints are conveniences that keep an agent's search in one place. They are not access control: every request is authorized against the identity behind it, whichever endpoint it reaches. A caller sees only what that identity may read.

In the Credible app, Connect AI prints the global URL and lets you switch to a narrower one. A shared workspace's Manage page and a package's settings show their own URLs. Your personal workspace has no workspace URL; use the global or organization URL.

Connecting Custom Agents

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

  • OAuth, as a person. Interactive MCP clients sign in through OAuth with dynamic client registration, and every call runs as that person. For a script a person runs, pass their access token:

    Authorization: Bearer <access-token>
  • API key, as a group. For agents and services that run without a person signing in, use a group API key. The key acts as the group, with every role the group holds, so grant the group only what the agent needs. See Create an API Key.

    Authorization: ApiKey <api-key>

A group API key belongs to one organization, so use the organization, workspace or package endpoint with it.

Test the connection with curl

Initialize a session to check the credentials:

curl -X POST "https://<your-org>.mcp.credibledata.com/mcp" \
  -H "Authorization: ApiKey ${CREDIBLE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test-client", "version": "1.0.0" }
    }
  }'

Then list the tools with the same headers and "method": "tools/list". The list matches the endpoint, as in the table below.

Tool Reference

ToolGlobal endpointOrganization, workspace and package endpoints
get_contextYes (with organization and workspace)Yes
execute_queryYes (with organization)Yes
search_malloy_docsYesYes
get_skillYesNo
search_credible_docsNoYes

The global endpoint has no organization in its hostname, so its get_context and execute_query take the organization as a parameter. Otherwise the parameters are the same. Every tool also takes an optional header: a short line describing the call, shown to the person in clients that display it.

get_context

Finds the sources, fields, views and values a question needs, or lists what is in scope. It returns model context, not a query: the agent writes the query from what comes back.

Parameters, all optional:

  • search_targets: an array of things to find, one per concept. Each target has:
    • target_type (required): source, dimension, measure, view or dimensional_value.
    • search_text: what to match, by meaning. For a dimensional_value target, the value the person named.
  • scopes: an array that narrows the search to packages, model files or sources. Each scope has environment and package (required), and optionally version, model_path, source and entity_name.
  • environment: an environment to search in, or to list the packages of.
  • givens: values for the model's given: parameters, keyed by name.
  • user_prompt: the person's question, word for word, to help rank results.
  • limit and offset: page through a source listing. Leave limit out unless you need paging.
  • filter_params: values for sources that use the deprecated #(filter) annotation.
  • organization (global endpoint only): the organization to search. Leave it out to use your only organization, or to get a list when you have several.
  • workspace (global endpoint only): limit the call to the packages in one shared workspace.

Called without search_targets, get_context lists one level down from the scope instead of searching: organizations, environments, packages, sources, then fields. A level with only one choice is entered rather than listed.

The response has sources, an array in rank order. Each source carries source_info (its resource_id, summary, docs, and the givens it takes) and entities, the matching fields with their name, type, description and, for indexed dimensions, sample values. Listing responses set listing and return organizations, environments or packages instead. On the global endpoint, the response's organization is the value to pass to execute_query. The full response schema is in the Retrieval API Reference.

execute_query

Runs a Malloy query against a published model, as the caller, and returns the result rows with rendering metadata.

Parameters:

  • environment (required): the environment the package is in.
  • package (required): the package.
  • model_path (required): the .malloy file within the package, for example model.malloy.
  • query: a Malloy query, starting run: <source> -> { ... }. Use either query or query_name.
  • query_name: a view or named query defined in source. Requires source.
  • source: the source that defines query_name. Leave it out with query.
  • version: a package version. Leave it out to use the package's latest version.
  • givens: values for the model's given: parameters, keyed by name.
  • filter_params: values for the deprecated #(filter) annotation.
  • expanded: in clients that render results, show this result open instead of collapsed.
  • organization (global endpoint only, required): the organization from the get_context response.

Copy environment, package, model_path, source and version from the resource_id that get_context returned.

get_skill

Global endpoint only. Returns Credible's analysis guides, the same skills the Credible plugin installs, for clients that can't install skills. With no skill_name, it lists the available skills. With skill_name, it returns that guide as Markdown. A guide's reference files are fetched the same way, as <skill>/<file>.

search_malloy_docs

Searches the Malloy language documentation. Takes query (required), a question in plain language.

search_credible_docs

Searches the Credible documentation. Takes query (required), a question in plain language. Not on the global endpoint.

Errors

The server returns standard MCP errors for invalid requests, failed authentication and failed queries. An agent can read a failed query's error, correct the query and call again.

Next Steps

On this page