@matihlabs/mcp

@matihlabs/mcp

Connect AI clients (Claude Desktop, ChatGPT, Cursor, …) to the Matih data platform over the Model Context Protocol. Write SQL, profile tables, run analyses + charts, manage dashboards, and upload files — all through MCP tools, with OAuth/PKCE auth and PII-safe egress.

New here? See QUICKSTART.md for a step-by-step customer guide — create a token, connect Claude Desktop / Cursor, and copy-paste curl smoke tests — plus a troubleshooting table.

Use as a stdio MCP server (Claude Desktop / Cursor)

Add to your client's MCP config. The token is delivered via the environment — never as a CLI flag (which leaks into the OS process list):

{
  "mcpServers": {
    "matih": {
      "command": "npx",
      "args": ["-y", "@matihlabs/mcp", "https://<slug>.app.matih.ai/api/v1/mcp"],
      "env": { "MATIH_MCP_TOKEN": "<your Matih bearer token>" }
    }
  }
}

The bridge turns the remote Matih HTTP MCP endpoint into a local stdio MCP server, forwarding every tools/call, resources/read, and prompts/get to Matih.

Endpoint: replace <slug> with your workspace slug — your Matih app lives at https://<slug>.app.matih.ai (the bare app.matih.ai host does not resolve). Get a mat_agt_… token from Settings → Developer Tokens. See QUICKSTART.md for the full walkthrough.

Use as a library

import { McpClient, MatihTools, StaticTokenProvider } from "@matihlabs/mcp";

const client = new McpClient({
  endpoint: "https://<slug>.app.matih.ai/api/v1/mcp",
  tokenProvider: new StaticTokenProvider(process.env.MATIH_MCP_TOKEN!),
});

// discovery-first: fetch the LIVE tool surface (auto-initializes + caches)
const live = await client.tools();
console.log(live.map((t) => t.name));

// call ANY tool generically — including Beta tools with no typed wrapper
const hot = await client.callTool("get_hot_context", {});

// typed convenience wrappers for the 34 STABLE tools
const graph = await new MatihTools(client).exploreGraph({ query: "orders", depth: 2 });
const matih = new MatihTools(client);
const result = await matih.runSql({ connection_id: "<id>", sql: "select 1" });

OAuth (PKCE) instead of a static token

import { McpClient, OAuthTokenProvider } from "@matihlabs/mcp";

const tokenProvider = new OAuthTokenProvider({
  resourceMetadataUrl: "https://<slug>.app.matih.ai/.well-known/oauth-protected-resource/api/v1/mcp",
  clientId: "<registered client id>",
  acquire: async ({ metadata, clientId, resource }) => {
    // open metadata.authorization_endpoint (PKCE S256, resource=<resource>),
    // capture the code at your redirect_uri, return { code, verifier, redirectUri }.
  },
});

The provider runs RFC 9728 → RFC 8414 discovery, PKCE S256, RFC 8707 resource-bound tokens, caches, and refreshes; a 401 invalid_token triggers one re-auth.

Tools

Discovery is the primary API — await client.tools() returns the live tool descriptors and client.callTool(name, args) reaches every advertised tool. The typed facade (MatihTools) covers the 34 stable tools (STABLE_TOOL_NAMES):

• Query & SQL: ask (natural-language → grounded answer + the SQL it ran), run_sql, run_analysis, get_query_result, export_result
• Catalog & discovery: list_connections, list_databases, list_schemas, list_tables, describe_table, profile_table
• Ontology & semantic layer: search_ontology, get_entity, get_relationships, get_semantic_model, get_glossary, explore_graph
• Governed metrics & taxonomy: get_metric, run_metric, draft_metric (write-class — proposes a DRAFT metric_def into the human-gated DRAFT → REVIEW → APPROVED → SHIP pipeline), list_metric_drafts, export_semantic_model (OSI), get_taxonomy, export_taxonomy (SKOS)
• Dashboards & charts: create_chart, create_dashboard, get_dashboard, publish_dashboard
• Uploads: upload_file, upload_status, create_upload_url, finalize_upload
• Identity & scope: whoami, get_scope

The 1 Beta tool (BETA_TOOL_NAMES: get_hot_context) is deliberately not hard-typed while its shape may evolve — call it via client.callTool(name, args). The governed metrics & taxonomy group and explore_graph were promoted from Beta to stable in July 2026 (PDR W3-1).

Plus catalog / lineage resources and the explain_metric prompt. Every tool is bounded by the developer token's scope (connections + capabilities you grant in Settings) and never exceeds your own permissions — get_scope shows exactly what a token allows.

Notes

• Egress consent. Matih gates third-party-LLM data egress per tenant. If your tenant hasn't accepted the data-processing agreement, calls return a clear EGRESS_CONSENT_REQUIRED error with a link to accept it.
• Node ≥ 20 (uses native fetch + node:crypto; zero runtime dependencies).

License: Apache-2.0 · https://matih.ai