# mcp [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/matih-labs/matih-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-16

## Description
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.

## Tools
Capabilities this server exposes over MCP:

- **ask**
- **list_connections**
- **list_databases**
- **list_schemas**
- **search_ontology**
- **get_entity**
- **get_metric**
- **run_metric**
- **draft_metric**
- **create_chart**
- **create_dashboard**
- **get_dashboard**
- **upload_file**
- **upload_status**
- **create_upload_url**
- **finalize_upload**
- **whoami**
- **get_scope**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp": {
    "command": "npx",
    "args": ["-y","@matihlabs/mcp","https://<slug>.app.matih.ai/api/v1/mcp"]
  }
}
```

## Documentation & README

# @matihlabs/mcp

Connect AI clients (Claude Desktop, ChatGPT, Cursor, …) to the **Matih** data
platform over the [Model Context Protocol](https://modelcontextprotocol.io). 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](./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):

```json
{
  "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](./QUICKSTART.md) for the full walkthrough.

## Use as a library

```ts
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

```ts
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