MCP Tool Reference

The complete reference for the Colrows MCP tools - the six-tool catalog, request arguments, scopes, the request and response envelope, error codes, and clarification & continuation. It applies identically whether you call over JSON-RPC (see the MCP integration guide) or over the plain-REST wrapper documented here - one HTTP request per tool, no JSON-RPC.

Endpoint

POST https://cloud.colrows.com/api/mcp/mcp-clients/tools/{toolName}
Content-Type: application/json
Authorization: Bearer <mcp-access-token>

POST /api/mcp/mcp-clients/tools/askData

{
  "datasourceId": "238b1c06-a155-4fc3-b229-2cc657500891",
  "schema": "public",
  "question": "Which is our best product by order volume?",
  "maxRows": 10
}

Authentication

Use the same MCP OAuth access token described in the MCP integration guide:

Authorization: Bearer cr_mcp_at_...

Access tokens expire after 15 minutes. Refresh with grant_type=refresh_token against the Colrows OAuth token endpoint (/api/oauth/token) instead of forcing the user through the browser flow again.

Tool catalog

Six read-only tools. The names and order match MCP tools/list.

No tool accepts SQL text. Call listDatasources to get IDs for the query tools. askMetadata uses all accessible datasources unless you supply IDs.

Examples

List datasources

POST /api/mcp/mcp-clients/tools/listDatasources

{}

Returns data as an array of { "datasourceId", "name" } for every datasource the caller may read.

Ask metadata

POST /api/mcp/mcp-clients/tools/askMetadata

{
  "question": "Where can I find revenue, and how do orders join customers?",
  "datasourceIds": ["238b1c06-a155-4fc3-b229-2cc657500891"]
}

Returns data.answer as text, or a clarification. datasourceIds and schema are optional; omit datasourceIds to use every accessible datasource.

Ask data

POST /api/mcp/mcp-clients/tools/askData

{
  "datasourceId": "238b1c06-a155-4fc3-b229-2cc657500891",
  "schema": "public",
  "question": "Show monthly net revenue for this year",
  "maxRows": 100
}

askData does not accept SQL text. Colrows generates the SQL, validates it, executes it under the caller's data-access rules, and returns the generated sql, an optional executionId, a confidenceScore and explanation, semantic sources, columns (each with columnName and javaScriptType), rows, rowCount, and a truncated flag. Each source carries its entity type plus available names and descriptions; source IDs are omitted. maxRows defaults to 1000 and cannot exceed 5000.

Verified queries

Curators create and edit Verified Queries on the Verified Queries page or through the Verified Queries REST API. They follow the same versioning, lineage, and semantic-validity rules as other semantic entities. Only the latest valid version of a query can be found or run. Unlike askData, which sends each question for fresh SQL generation, these three tools find and run stored, curator-approved SQL.

A verified query can declare typed parameters, written in its SQL as :name placeholders. The caller supplies values for them; the saved SQL never changes. Parameter types are STRING, INTEGER, DECIMAL, BOOLEAN, DATE and TIMESTAMP.

Use the tools in this order: search for a query, optionally get its current definition, then run it.

Search verified queries

Scope metadata:read. question is required; datasourceId is optional; limit defaults to 5 and cannot exceed 20.

POST /api/mcp/mcp-clients/tools/searchVerifiedQueries

{ "question": "Revenue for the West region this year", "datasourceId": "sales-prod", "limit": 5 }

The result contains matches. Each match has queryId, version, label, question, datasourceId, an optional schema, and parameters (each with name, type and an optional description). Search doesn't return SQL text or run a query, and it searches only datasources the caller can access.

{
  "matches": [
    {
      "queryId": "query-id",
      "version": 2,
      "label": "Revenue by region",
      "question": "What is the revenue for a region from a given date?",
      "datasourceId": "sales-prod",
      "schema": "public",
      "parameters": [
        { "name": "region", "type": "STRING", "description": "Sales region" },
        { "name": "from_date", "type": "DATE", "description": "First date to include" }
      ]
    }
  ]
}

Get a verified query

Scope metadata:read. Returns the current valid version of one query the caller can access, with the same fields as a search match. Use it to refresh the version and parameters, for example after a VERSION_CHANGED error. It doesn't return SQL text.

POST /api/mcp/mcp-clients/tools/getVerifiedQuery

{ "queryId": "query-id" }

Execute a verified query

Scope data:query. queryId and the current version are required. Put exactly the declared parameters in params, and omit params for a query without parameters. maxRows defaults to 1000 and cannot exceed 5000.

POST /api/mcp/mcp-clients/tools/executeVerifiedQuery

{
  "queryId": "query-id",
  "version": 2,
  "params": { "region": "West", "from_date": "2026-01-01" },
  "maxRows": 100
}

The server loads the stored SQL; the caller can't submit SQL text. The result contains queryId, version, datasourceId, the saved SQL template in sql (parameter values are not written into it), columns, rows, rowCount, and a truncated flag. The query's validity and the caller's data access are checked when it runs, and the normal execution path applies row and column policies, read-only checks and the query cost guard.

A missing, extra or wrongly typed parameter fails with INVALID_INPUT. If the stored version is newer than the one you sent, the call fails with VERSION_CHANGED: call getVerifiedQuery and try again with the current version.

Response envelope

The REST endpoint returns the same tool-call envelope as MCP.

Success:

{
  "structuredContent": { "data": { /* tool-specific result */ } },
  "content": [{ "type": "text", "text": "{\"data\":{...}}" }],
  "isError": false
}

Tool error - the message stays generic and carries no internal detail, and the kind travels in _meta["colrows/errorCode"]:

{
  "content": [{ "type": "text", "text": "You do not have access to the data this request needs" }],
  "isError": true,
  "_meta": { "colrows/errorCode": "ACCESS_DENIED" }
}

HTTP status is normally 200 for both tool-level success and tool-level error - check isError, not just the status code. Authentication, authorization, and malformed request bodies use HTTP error statuses instead.

Error codes

Clarification & continuation

Tools that interpret natural language - askMetadata and askData - may require clarification before Colrows can compile a proven query.

Clarification response:

{
  "structuredContent": {
    "data": {
      "status": "clarification_required",
      "continuationToken": "cr_mcp_cont_...",
      "expiresAt": 1782200000000,
      "clarification": {
        "id": "best-product-metric",
        "question": "Define what metric “best product” should mean for this query."
      }
    }
  },
  "isError": false
}

Resume by calling the same tool with the token and your answer:

POST /api/mcp/mcp-clients/tools/askData

{
  "continuationToken": "cr_mcp_cont_...",
  "clarificationResponse": { "answer": "Best product means highest order volume." }
}

If clarificationResponse is not an object, Colrows normalizes it to { "answer": <value> }. The original datasource, schema, and question stay bound to the token and are replayed automatically; do not send clarificationHistory yourself. You may set a new maxRows when you resume askData. Full continuation semantics (expiry, cross-node resume, replay rejection, three-round limit) are covered in the MCP integration guide.