ai.matih/mcp
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Open source Repository Open in the app JSON README (API)
About
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- ai.matih
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.2.1
- Forks
- 1
- Last push
- 2026-07-06T18:39:37Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 03:00:12
- Updated
- 2026-08-29 03:00:12
- Origin id
ai.matih/mcp
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