Gaur Docs

Exposes a consumer's contracts as a Model Context Protocol server. AI agents and MCP-aware tools connect here to discover and call contracts as tools. For a guided walkthrough, see Using MCP.

Endpoint

POST /v1/api/{consumer_slug}/mcp
Authorization: Bearer <api_key>

Path parameters

Parameter	Type	Description
`consumer_slug`	string	The slug of the consumer. The API key must authorize this consumer, and the consumer must have the MCP server protocol enabled.

Transport

You don't call the endpoint directly; point an MCP client or agent framework at it and let the client handle the protocol handshake and message framing.

Requirement	Detail
Authentication	`Authorization: Bearer <api_key>` on every request.
Session	Tracked with the `mcp-session-id` header. Conformant MCP clients manage this automatically.
Protocol enabled	The consumer must have the MCP server protocol enabled, or the endpoint returns `403`.

Client configuration

Most MCP clients take a server entry with a URL and headers:

{
  "mcpServers": {
    "gaur": {
      "url": "https://<base-url>/v1/api/<consumer_slug>/mcp",
      "headers": { "Authorization": "Bearer <api_key>" }
    }
  }
}

The exact format depends on the client. See Using MCP for snippets per client.

Tools

Which tools are registered depends on the consumer's query mode.

Tool	Contract-only	Contract-with-SQL-fallback	SQL-only
`search_objects`	✓	✓	✓
`describe_object`	✓	✓	✓
`query_contract`	✓	✓
`execute_sql`		✓	✓

search_objects

Finds data objects (contracts, tables, models, collections) relevant to a question, using hybrid semantic and keyword search.

Argument	Description
`query`	A rich natural-language phrase describing what to find.
`keywords`	Two to four short keywords to focus the search.
`object_types`	Optional list of types to filter to. Types not allowed by the consumer's query mode are rejected with a `Forbidden` error.

Fetches full context for one object by id and type: Object Info, Business Context, and (for a contract) the contract JSON, which includes its dimensions, measures, and the field rules needed to call query_contract. Returned object types are gated by query mode.

query_contract

Runs a structured query against a named contract. Registered in contract-only and contract-with-SQL-fallback modes.

Argument	Description
`contract_name`	Name of the contract to query.
`query`	Query specification conforming to the Query schema.
`context`	Optional object of values for the contract's row-level security.

Result:

Field	Description
`contract_name`	The contract that ran.
`query`	The query that was executed (echoed back).
`rows`	The result rows.
`columns`	The result columns.
`row_count`	Number of rows returned.
`execution_time_ms`	Execution time in milliseconds.
`has_next_page`	Whether more rows are available.

execute_sql

Executes a read-only (SELECT or WITH) SQL query against the consumer's authorized tables and models. Every referenced object is checked against the consumer's scope and any configured RLS rules before execution. Registered in SQL-only and contract-with-SQL-fallback modes.

Argument	Description
`sql`	The SQL statement. Must start with `SELECT` or `WITH`.
`context`	Optional object of values for RLS.

Result:

Field	Description
`sql`	The SQL that ran.
`rows`	The result rows.
`columns`	The result columns.
`row_count`	Number of rows returned.
`execution_time_ms`	Execution time in milliseconds.

Resources

The server publishes MCP resources under gaur://consumer/{slug}/.... Conformant clients list them in their resources panel and read them on demand:

URI	Returns
`gaur://consumer/{slug}/manifest`	Consumer manifest JSON: slug, name, enabled protocols, endpoint URLs, auth shape, query mode.
`gaur://consumer/{slug}/docs`	All-in-one markdown briefing: endpoints, auth, contracts in scope, OpenAPI and docs URLs.
`gaur://consumer/{slug}/contracts`	List of contracts available to this consumer. Contract modes only.
`gaur://consumer/{slug}/contracts/{contract_name}`	Full JSON for one contract in scope. Contract modes only.
`gaur://consumer/{slug}/query-schema`	JSON Schema for a `query_contract` request. Contract modes only.

The contract-related resources are present only when the consumer's query mode exposes contracts.

Governance

Every tool call is bound by the consumer's scope, query-mode gating, and the contracts' row-level security. Tools return governed contract data, never raw, unscoped database access. See Using MCP.

Status codes

Status	Meaning
`200`	Success.
`401`	Missing or invalid API key.
`403`	The API key does not authorize this consumer, or MCP is not enabled for it, or a tool argument referenced an object type forbidden by the consumer's query mode.
`500`	Internal server error.

MCP endpoint