Skip to main content
Glama
@matihlabs/mcp

@matihlabs/mcp

Official
by matih-labs

@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.

Related MCP server: Heavenly Health Protocol

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Production-ready MCP server that enables AI assistants to seamlessly interact with SAP Datasphere environments for real tenant data discovery, metadata exploration, analytics operations, ETL data extraction, database user management, data lineage analysis, and column-level data profiling.
      39
      64 npm
      333 PyPI
      50
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to securely access, query, and mutate normalized user-controlled health data (e.g., from Apple Health or Supabase) through a bounded set of MCP tools, with optional OAuth and sandboxed deployment.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Aidlab wellness data to AI tools through MCP, providing read-only access to daily summaries, steps, heart rate, HRV, sleep, activities, and profile with OAuth authentication.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides an OAuth-protected, scoped, and audited MCP server that lets AI assistants safely query business data through a fixed set of tools without direct database access.
      1
      MIT