Using MCP

A Gaur consumer can expose its contracts as an MCP server, using the Model Context Protocol, the open standard for giving AI agents access to tools and data. An MCP-aware agent connects to a consumer and gets a small governed toolset for finding and querying that consumer's contracts, all inside the consumer's governance.

What an agent gets

Connect over MCP and the agent doesn't get raw database access. It gets a small, governed toolset. The tools available depend on the consumer's query mode:

A typical agent flow: search for relevant objects, describe the chosen contract (which includes its fields), then query it.

Query-mode gating

search_objects and describe_object filter what they return by the consumer's query mode. On a contract-only consumer, asking either tool for raw tables or models returns a Forbidden error: an agent there should only see contracts. This is enforced server-side; an agent can't trick it. Query mode also decides which query tool is registered: query_contract for contract modes, execute_sql for SQL modes, both for contract-with-SQL-fallback.

The endpoint

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

It speaks MCP over streamable HTTP. You don't call it by hand; you point an MCP client at the URL and let it handle the protocol.

Requirements:

• The consumer must have the MCP server protocol enabled (see Consumers). Otherwise the endpoint returns 403.
• Every request must carry a valid API key for the consumer.

Sessions are tracked with an mcp-session-id header, which conformant MCP clients manage for you.

Connecting an MCP client

Most MCP clients take a server entry with a URL and an Authorization header. The exact file and field names differ from client to client; the patterns for the common ones are below.

In every example, replace <base-url>, <consumer_slug>, and <api_key> with values from your workspace. Treat <api_key> as a secret: don't commit configuration files that contain it. Several of these clients support expanding environment variables in their config, which is the safer pattern for shared repos.

Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project. Add Gaur as an entry under mcpServers:

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

Restart Cursor (or reload MCP servers from the settings panel) and the Gaur tools become available to the agent.

Claude Code

Claude Code speaks MCP natively. Add Gaur with claude mcp add:

claude mcp add --transport http gaur \
  https://<base-url>/v1/api/<consumer_slug>/mcp \
  --header "Authorization: Bearer <api_key>"

The server is then available in every Claude Code session. Scope it to a project by running the command from that project's directory, or with --scope project.

Claude Desktop

Claude Desktop reads MCP servers from its config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop after editing the file.

Opencode

Opencode takes MCP servers under the mcp key of its config (opencode.json in your project, or the global config):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gaur": {
      "type": "remote",
      "url": "https://<base-url>/v1/api/<consumer_slug>/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Codex CLI

The OpenAI Codex CLI reads MCP servers from ~/.codex/config.toml. Remote HTTP servers go under [mcp_servers.<name>]:

[mcp_servers.gaur]
url = "https://<base-url>/v1/api/<consumer_slug>/mcp"

[mcp_servers.gaur.headers]
Authorization = "Bearer <api_key>"

Anything else

For other MCP-aware clients (Continue, Zed, Windsurf, custom agents using the official MCP SDKs), the shape is the same: a streamable-HTTP server URL plus an Authorization header carrying the API key. Once connected, the client discovers the tools above automatically.

Discovery resources

The server also publishes MCP resources under gaur://consumer/{slug}/.... Conformant clients list these in their resources panel and read them on demand, which is how an agent (or you) orients to a consumer without a round of tool calls:

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

How MCP stays governed

An agent over MCP is bound by the same rules as any other consumer caller:

• It can only see and query the contracts the consumer is scoped to.
• The query mode decides which tools are available and what search_objects and describe_object can return.
• Row-level security applies to every result. Where a contract needs context for RLS, the agent supplies it through the request context the tools accept.
• Tool results are governed contract data, never raw, unscoped database access.

Query mode: bounded vs. unbounded generation

The consumer's query mode decides which tools an agent can usefully call, and that's the difference between bounded and unbounded generation:

• Contract-only mode is bounded. The agent works through query_contract: it picks a published contract and fills in a query spec that Gaur validates. Everything it can produce is shaped by a contract a builder authored. execute_sql is not registered on this surface. This is the mode for agents embedded in customer-facing products or any otherwise-untrusted surface.
• SQL modes are unbounded. When the consumer permits SQL, the agent can call execute_sql and compose queries freely, so generation is open-ended. It stays safe in terms of access: the SQL is read-only, restricted to the objects the consumer is scoped to (never your whole database), and validated against the consumer's scope and RLS rules before it runs. But the shape of a query is no longer bounded by a contract.

So you can connect an agent to production data with confidence. The agent operates inside the boundary a builder defined, not around it.

When to use MCP

Next