MCP integration

Overview

Connect ChatGPT, Claude, or another compatible MCP client to query your Loam data through the Model Context Protocol (MCP) resource. Loam has one configured URL for compatible clients. OAuth asks you to choose My account or one currently eligible Agent; it does not create a per-user, per-workspace, or per-Agent endpoint. The resource uses JSON-RPC 2.0 over Streamable HTTP.

Once connected, your AI can list permitted Tables, inspect schemas, run read-only SQL queries, and, with separately consented write access, change permitted rows and Table schemas. The OAuth authorization authenticates that one selected principal and may only narrow its live grants; it never owns copied grants.

Always copy the configured resource from Loam or use discovery. Do not derive a hostname or append a workspace public ID, principal ID, or credential ID.

Choose the account to connect

In Loam, go to Settings > Connect AI and copy the configured URL. During OAuth, Loam shows your eligible workspace accounts. Choosing My account uses your own current groups and grants. Choosing an Agent uses only that Agent's direct grants and explicit permission groups; your personal authority is not added.

Alice and Bob can independently authorize the same Finance Agent. Each receives a separate authenticator and refresh family, so either human can revoke their own connection without revoking the other connection or the Agent.

Connect AI lists each authorization's selected account, current eligibility, effective access, restrictions, and optional ceiling. Changing accounts requires a new OAuth authorization.

Configured resource

https://www.loamdata.com/mcp

The resource accepts JSON-RPC 2.0 requests and uses OAuth 2.1. Compatible MCP clients discover Loam's authorization server and prompt you to authorize when you add the server URL. The token audience is bound to this exact configured resource.

OAuth and discovery

Start with the configured resource. Discovery returns its exact value; clients must not synthesize a URL from account choices:

/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server
/oauth/register
/oauth/authorize
/oauth/token
/oauth/revoke

The server-held OAuth challenge binds the resource, client, redirect, state, and PKCE values. Loam derives the related human from the verified session and rejects caller-supplied actor or principal substitutions.

Connecting ChatGPT

1. In Loam, go to Settings > Connect AI and copy the configured MCP resource URL.
2. In ChatGPT on the web, open Settings > Apps > Advanced settings and turn on Developer mode.
3. Under Apps, click Create app. Paste your Loam connection URL as the remote MCP server endpoint and choose OAuth when prompted.
4. Save or publish the app according to your workspace rules. Developer mode availability and publishing requirements vary by plan, and your workspace administrator may need to enable it.
5. Start a new chat, select the Loam app from the tools menu, and complete the OAuth flow when prompted.

For detailed steps with screenshots, see the How to connect ChatGPT help article.

Connecting Claude

Add Loam as a custom connector in Claude on the web or Claude Desktop. Remote OAuth servers such as Loam are not configured in claude_desktop_config.json.

1. In Loam, go to Settings > Connect AI and copy the configured MCP resource URL.
2. In Claude, open Settings > Connectors and click Add custom connector.
3. Paste your Loam connection URL, click Add, and complete the OAuth sign-in.
4. In a chat, open the tools menu and enable Loam under Connectors for that conversation.

For detailed steps, see the How to connect Claude help article.

Available MCP tools

Every connection receives mcp:read. A connection receivesmcp:write only after separate consent. Read-only authorizations do not list or run mutating tools. Each call still uses the OAuth-selected principal's current authority and transport restrictions.

Loam's ordinary MCP surface also includes bounded data-cleaning tools. They can list and profile governed datasets, find exact duplicate groups, preview a closed cleaning plan, save a reviewed plan as a new source-preserving View, and compare source with output. These tools use the same regional engine, OAuth audience, grants, and deployment as the rest of Loam. No acquisition minisite owns a regional backend or MCP proxy. Fuzzy matching and whitespace rewriting are not supported by the server plan.

These upload tools provide the signed-transfer lifecycle, not access to a path on your computer. The MCP client must run trusted desktop-local code that has a user-approved file handle and can perform the PUT. A remote connector by itself cannot upload a local file.

Mutation retries

Supply a stable operationKey for every execute_sql_mutation call. For row DML, an equivalent retry by the same authorization uses Loam's durable replay contract; reusing the key for different SQL conflicts. For CREATE NAMESPACE, CREATE TABLE, ALTER TABLE, and DROP TABLE, the key is audit correlation only. If a DDL response is lost or ambiguous, list the catalog and inspect the Table schema before deciding whether another mutation is needed. Do not retry DDL blindly.

Programmatic MCP client

If you are building a custom AI connection, complete the MCP OAuth flow for the selected account, then connect with an MCP SDK that supports Streamable HTTP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const accessToken = process.env.LOAM_MCP_OAUTH_ACCESS_TOKEN;
if (!accessToken) throw new Error("LOAM_MCP_OAUTH_ACCESS_TOKEN is required");

const transport = new StreamableHTTPClientTransport(
  new URL("https://www.loamdata.com/mcp"),
  {
    requestInit: {
      headers: { Authorization: "Bearer " + accessToken },
    },
  },
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Execute a read-only SQL query
const result = await client.callTool({
  name: "execute_sql_query",
  arguments: { sql: "SELECT * FROM commerce.sales.production.charges LIMIT 5" },
});
console.log(result);

Authentication

The configured MCP resource uses OAuth 2.1. When you add it to a compatible MCP client, the client starts Loam's authorization flow automatically. The consent page selects one workspace-qualified human or eligible Agent account without copying grants.

The OAuth access token used by an MCP client is a regional machine authenticator. It is distinct from the Supabase access JWT used by a signed-in person to approve the connection, and it is not produced by a human-token exchange.

OAuth-issued MCP access tokens are short lived. A token identifies the selected effective principal and related human, and carries the exact configured-resource audience and MCP transport purpose. It does not contain permissions, grants, groups, or a snapshot of authority.

Permissions

Each authorization receives the same Viewer, Editor, or Data admin data-permission ceiling available to a personal API key. That ceiling intersects the ordinary Engine allow and deny grants attached to the selected principal. A human uses their direct grants, current groups, and Everyone lane. An Agent uses its direct grants and only explicit Agent permission groups, never Everyone or the related human's groups. Row mutations require live authority on every referenced Table. Namespace creation requires Data admin on the parent. Table schema mutations require their applicable live schema-management authority and entitlement. Mutating tools additionally require separately consented mcp:write.

On every operation, Loam rechecks the authorization, selected principal, groups, grants, capabilities, entitlement, optional ceiling, transport restrictions and, for an Agent, the related human's current use eligibility. The human affects eligibility and audit only, never Agent data authority. Query execution and catalog discovery use this same core authorization path. Catalog tools read current paths from the generic node tree; moving or renaming a Namespace changes the next listed path without changing a Table or View's stable regional node ID. A query-only AST gate still rejects every SQL mutation sent to execute_sql_query. The separate execute_sql_mutation tool parses one statement and admits only its documented row and Table allow-list. It cannot change permissions, switch workspaces, bypass a deny, or mutate system-owned integration Tables. See Grants & Permissions for details.