matih

@matihlabs/mcp

通过 Model Context Protocol，将 AI 客户端（Claude Desktop、ChatGPT、Cursor，……）连接到 Matih 数据 平台。编写 SQL、分析表格、运行分析并生成图表、管理仪表板和上传文件 — 所有操作均通过 MCP 工具完成，并采用 OAuth/PKCE 身份验证和 PII 安全出站机制。

初次使用？ 请参阅 QUICKSTART.md，获取分步客户 指南 — 创建令牌、连接 Claude Desktop / Cursor，并复制粘贴 curl 冒烟测试 — 以及故障排除表。

用作 stdio MCP 服务（Claude Desktop / Cursor）

将以下内容添加到客户端的 MCP 配置中。令牌通过环境变量传递 — 切勿将其用作 CLI 标志（否则会泄露到操作系统进程列表中）：

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

此桥接程序会将远程 Matih HTTP MCP 端点转换成本地 stdio MCP 服务， 并将每个 tools/call、resources/read 和 prompts/get 请求转发给 Matih。

端点： 将 <slug> 替换为你的工作区 slug — 你的 Matih 应用位于 https://<slug>.app.matih.ai（裸域名 app.matih.ai 无法解析）。 从 Settings → Developer Tokens 获取 mat_agt_… 令牌。完整操作步骤请参阅 QUICKSTART.md。

用作库

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）代替静态令牌

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 }.
  },
});

该提供程序会执行 RFC 9728 → RFC 8414 发现、PKCE S256、RFC 8707 资源绑定令牌的缓存和刷新；遇到 401 invalid_token 时会触发一次重新身份验证。

工具

发现是主要 API — await client.tools() 会返回实时工具描述符，而 client.callTool(name, args) 可调用所有已公布的工具。 类型化门面（MatihTools）涵盖 34 个稳定工具 （STABLE_TOOL_NAMES）：

• 查询与 SQL： ask（自然语言 → 有依据的答案 + 执行过的 SQL）、 run_sql、run_analysis、get_query_result、export_result
• 目录与发现： list_connections、list_databases、list_schemas、 list_tables、describe_table、profile_table
• 本体与语义层： search_ontology、get_entity、 get_relationships、get_semantic_model、get_glossary、explore_graph
• 治理指标与分类体系： get_metric、run_metric、draft_metric （写入类 — 将 DRAFT metric_def 提案提交至由人工把关的 DRAFT → REVIEW → APPROVED → SHIP 流程）、list_metric_drafts、 export_semantic_model（OSI）、get_taxonomy、export_taxonomy（SKOS）
• 仪表板与图表： create_chart、create_dashboard、get_dashboard、 publish_dashboard
• 上传： upload_file、upload_status、create_upload_url、finalize_upload
• 身份与范围： whoami、get_scope

1 个 Beta 工具（BETA_TOOL_NAMES：get_hot_context）的结构可能会变化，因此不会为其定义固定类型 — 请通过 client.callTool(name, args) 调用。治理指标与分类体系组以及 explore_graph 已于 2026 年 7 月从 Beta 升级为稳定版（PDR W3-1）。

此外，还提供目录 / 血缘资源和 explain_metric 提示词。每个 工具都受开发者令牌范围限制（你在 Settings 中授予的连接 + 功能），且不会超出你自身的权限 — get_scope 会准确显示令牌允许的操作。

说明

• 出站同意。 Matih 会按租户控制向第三方大模型传输数据。如果你的 租户尚未接受数据处理协议，调用会返回清晰的 EGRESS_CONSENT_REQUIRED 错误，并附上接受协议的链接。
• Node ≥ 20（使用原生 fetch + node:crypto；运行时零依赖）。

许可证：Apache-2.0 · https://matih.ai