Metabase

Máy chủ MCP Metabase

Metabase bao gồm một máy chủ Model Context Protocol (MCP) tích hợp cho phép các ứng dụng AI kết nối trực tiếp đến một phiên bản Metabase. Nó sử dụng Streamable HTTP transport và được xây dựng dựa trên Agent API của Metabase để cung cấp các công cụ tìm kiếm, điều hướng, truy vấn, trực quan hóa và tạo/cập nhật nội dung - tất cả đều được giới hạn theo quyền của người dùng đang kết nối.

Điểm cuối

Máy chủ MCP có sẵn tại:

https://{your-metabase.example.com}/api/metabase-mcp

Đường dẫn /api/mcp cũ vẫn hoạt động như một bí danh cho các ứng dụng hiện có, nhưng /api/metabase-mcp là URL chuẩn để quảng bá.

Kết nối ứng dụng

Trỏ bất kỳ ứng dụng tương thích MCP nào đến điểm cuối /api/metabase-mcp. Ví dụ: với Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Đối với Claude Desktop, hãy tạo một trình kết nối tùy chỉnh sử dụng cùng URL đó.

Đối với Cursor, mở Settings > MCP và thêm một máy chủ mới với loại được đặt thành streamable-http và URL:

https://{your-metabase.example.com}/api/metabase-mcp

Xác thực

Các ứng dụng MCP xác thực qua OAuth 2.0. Metabase chạy máy chủ OAuth nhúng của riêng mình - không cần nhà cung cấp bên ngoài.

Quy trình cho lần kết nối đầu tiên:

1. Ứng dụng khám phá các điểm cuối OAuth của Metabase.
2. Ứng dụng tự đăng ký với Metabase.
3. Người dùng được chuyển hướng đến Metabase để đăng nhập và phê duyệt kết nối.
4. Ứng dụng nhận được mã thông báo truy cập được giới hạn theo quyền của người dùng trên Metabase.

Các phiên dựa trên trình duyệt (xác thực cookie), khóa API và mã thông báo mb:full không có phạm vi MCP, vì vậy chúng có thể kết nối nhưng không thể gọi công cụ nào được giới hạn.

Phạm vi

Mã thông báo truy cập được giới hạn để hạn chế những công cụ mà ứng dụng có thể sử dụng:

Phạm vi	Công cụ được cấp
agent:content:read	browse_collection, browse_data, get_content, get_parameter_values, glossary, learn, search và tài nguyên dữ liệu catalog://metabase/fields (xem Resources)
agent:content:write	bookmark_content, collection_write, dashboard_write, document_write, duplicate_content, measure_write, metric_write, question_write, segment_write
agent:delivery:write	alert_write, subscription_write
agent:query:run	execute_query, refresh_ui_credential, render_drill_through, run_saved_question, visualize_query
agent:sql:run	execute_sql

Một công cụ chỉ khớp với phạm vi chính xác trong bảng. Ký tự đại diện như * hoặc agent:* và sentinel ::unrestricted không phải là phạm vi MCP, vì vậy chúng không cấp công cụ nào.

Các phạm vi này chỉ giới hạn bề mặt MCP. Không có điểm cuối REST nào có thể khai báo một trong số chúng là :scope của mình, vì vậy mã thông báo mới được cấp cho ứng dụng MCP không cấp quyền gì trên REST API.

scopes_supported của siêu dữ liệu tài nguyên được bảo vệ và scope của thử thách 401 đều liệt kê mọi phạm vi trong bảng, vì vậy kết nối mới yêu cầu tất cả chúng. Một số ứng dụng không nâng cấp sau 403: kết nối lại thủ công từ cài đặt trình kết nối của Claude đăng ký một ứng dụng mới và yêu cầu chính xác những gì các danh sách này liệt kê. Khi chúng chỉ liệt kê đường cơ sở, lần kết nối lại đó không bao giờ cung cấp ghi, SQL thô hoặc phân phối, và người dùng không có cách nào để cấp chúng (ENG-11089). Siêu dữ liệu máy chủ ủy quyền cũng quảng bá tất cả chúng.

Đường cơ sở (agent:content:read agent:query:run) bị khóa trên màn hình đồng ý: khi ứng dụng yêu cầu một trong các phạm vi này, người dùng không thể bỏ chọn nó. agent:query:run nằm trong đường cơ sở để biểu đồ không bao giờ cần nâng cấp. Claude Desktop thử lại một công cụ sau khi nâng cấp qua một phiên không khai báo hỗ trợ MCP Apps, vì vậy một visualize_query được nâng cấp bị từ chối và biểu đồ của nó không bao giờ được nhúng.

Một lời gọi công cụ hoặc đọc tài nguyên dữ liệu mà mã thông báo thiếu phạm vi sẽ bị từ chối với HTTP 403 và thử thách WWW-Authenticate: Bearer error="insufficient_scope" có scope liệt kê các phạm vi v2 mà mã thông báo đã giữ cộng với phạm vi cần thiết, để ứng dụng có thể nâng cấp. Mỗi công cụ cũng khai báo phạm vi của mình trong securitySchemes, là bản nháp SEP-1488, được ChatGPT hỗ trợ. Nó không phải là một phần của MCP 2025-03-26 (phiên bản mà máy chủ này báo cáo) hoặc đặc tả công cụ cuối cùng 2026-07-28, vì vậy các ứng dụng khác khám phá phạm vi bị thiếu từ 403. Bên trong một lô JSON-RPC, việc từ chối là lỗi -32600 trong băng tần thay vào đó. Các lần đọc vỏ giao diện không bao giờ bị thử thách: xem Resources.

Siêu dữ liệu tài nguyên được bảo vệ OAuth có sẵn tại:

/.well-known/oauth-protected-resource/api/metabase-mcp

Trên màn hình đồng ý, mọi phạm vi mà ứng dụng yêu cầu đều được chọn sẵn và các phạm vi đường cơ sở cũng bị khóa. Chỉ các phạm vi còn được chọn mới được cấp và chỉ cho mã thông báo mà ủy quyền này tạo ra. Việc bỏ chọn không bao giờ ảnh hưởng đến mã thông báo mà ứng dụng đã có. Một phạm vi bị bỏ chọn không được Metabase ghi nhớ. Một 403 sau đó có thể kích hoạt nâng cấp khác trong các ứng dụng hỗ trợ nó. Các ứng dụng khác có thể yêu cầu ủy quyền lại thủ công. error_description của mỗi thử thách kết thúc bằng ghi chú rằng người dùng phải cấp quyền trên màn hình đồng ý.

Một số ứng dụng thay thế error_description của 403 bằng văn bản của riêng họ, vì vậy instructions của kết quả initialize giải thích lỗi phạm vi cho mô hình: lỗi xác thực thường có nghĩa là thiếu quyền thay vì phiên đăng nhập hết hạn, mô hình nên nêu tên công cụ hoặc tài nguyên bị lỗi và quyền mà nó yêu cầu, và người dùng cấp quyền bằng cách kết nối lại và để quyền được chọn trên màn hình đồng ý. Các hướng dẫn là một chuỗi tĩnh, giống nhau cho mọi người gọi: không có danh sách quyền theo từng kết nối.

Truy cập công cụ theo nhóm

Trên các phiên bản Enterprise có tính năng ai_controls, quản trị viên có thể thu hẹp bề mặt theo nhóm quyền tại Admin > AI > Usage controls > MCP tools access (hiển thị bất cứ khi nào máy chủ MCP bật, có hoặc không có nhà cung cấp LLM). Mỗi nhóm có một hàng trong mcp_group_permission cho biết thành viên của nhóm đó có thể kết nối hay không và theo từng tên công cụ, "yes" hoặc "no" rõ ràng của quản trị viên; công cụ không có mục nhập sẽ nhận giá trị mặc định mà tác giả của nó khai báo, vì vậy mọi deftool đều mang :default-access bắt buộc là :allowed hoặc :denied và công cụ phát hành sau đó nhận chính xác giá trị mặc định đó trong mọi nhóm cho đến khi quản trị viên ghi đè. Các mục nhập được khóa theo tên công cụ, vì vậy việc đổi tên công cụ cần :renamed-from với các tên trước đây của nó (mục nhập được lưu dưới tên cũ vẫn áp dụng và API quản trị trình bày nó dưới tên hiện tại), hoặc tác giả chấp nhận rằng mọi lựa chọn của quản trị viên cho nó bị loại bỏ; metabase.mcp.v2.tool-names-test ghim các tên trực tiếp để không điều nào xảy ra do vô tình. Chính sách hiệu lực của người dùng là tool_access của mỗi nhóm của họ có hàng bật MCP: MCP bật khi bất kỳ nhóm nào như vậy tồn tại và công cụ được phép khi bất kỳ nhóm nào trong số đó phân giải nó thành có. Các hàng một mình quyết định điều đó và chúng cũng ghi lại chế độ quyền: chế độ đơn giản (Administrators, All Users và All tenant users) hoặc chế độ cấp nhóm (mọi nhóm khác), là trạng thái trong đó All Users không có hàng. Một công tắc xóa các hàng của các nhóm mà chế độ mới ẩn và gieo các nhóm mà nó bật khi vào mà không có hàng (Data Analysts khi vào chế độ cấp nhóm, All Users và All tenant users khi rời khỏi nó) và PUT từ chối một nhóm mà chế độ hiện tại ẩn, vì vậy không có yêu cầu nào đọc chế độ được lưu trong bộ nhớ cache. Chính sách được áp dụng trên các phạm vi OAuth trong tools/list và tools/call (v2/registry.clj) và người dùng có nhóm không cấp quyền truy cập bị từ chối tại initialize và tại resources/read (cho các phiên được mở trước khi MCP bị tắt) với lỗi nêu rõ cách khắc phục. Các công cụ chỉ dành cho ứng dụng (_meta {:ui {:visibility ["app"]}}, tức là refresh_ui_credential) không có trên trang quản trị: chúng được phép trong khi chính sách cho phép bất kỳ công cụ MCP Apps nào. Người siêu dùng và người gọi nội bộ không bao giờ bị thu hẹp; OSS cho phép mọi thứ. Trên Enterprise, các hàng được lưu trữ được thực thi ngay cả khi không có tính năng ai_controls (mã thông báo hết hạn hoặc không thể xác minh giữ các hạn chế mà quản trị viên đã cấu hình); tính năng này chỉ giới hạn trang quản trị và API. Trình phân giải là permissions.clj (defenterprise, triển khai EE trong metabase-enterprise.mcp.permissions) và API quản trị là /api/ee/ai-controls/mcp-permissions.

Các công cụ có sẵn

Được tạo từ sổ đăng ký v2 (deftool). Phạm vi được nêu ở đây là những gì sổ đăng ký kiểm tra trước khi công cụ chạy; một số trình xử lý kiểm tra phạm vi sâu hơn khi chúng biết lời gọi làm gì - agent:sql:run khi nguồn phân giải thành SQL gốc (question_write) và agent:query:run cho việc thực thi mà cảnh báo hoặc đăng ký trì hoãn (alert_write, subscription_write). Những từ chối đó mang cùng thử thách 403 insufficient_scope. tools/list hiển thị mọi công cụ bất kể mã thông báo giữ gì và mã thông báo thiếu phạm vi có thể không gọi nó.

Công cụ	Phạm vi	Mô tả
alert_write	agent:delivery:write	Tạo hoặc cập nhật một cảnh báo: một thông báo được gửi theo lịch trình khi kết quả của một câu hỏi đã lưu đáp ứng một điều kiện.
bookmark_content	agent:content:write	Thêm hoặc xóa dấu trang trên nội dung cho người dùng đang gọi — cùng danh sách đánh dấu/yêu thích mà thanh bên Metabase hiển thị.
browse_collection	agent:content:read	Duyệt các bộ sưu tập theo cấu trúc — một id thống nhất trên mọi phân vùng: một id số, một entity_id 21 ký tự, "root" (được đặt lại gốc theo từng không gian tên), hoặc "trash" (nội dung đã lưu trữ, chỉ ở chế độ mục).
browse_data	agent:content:read	Duyệt hệ thống phân cấp dữ liệu: cơ sở dữ liệu → lược đồ → bảng → trường.
collection_write	agent:content:write	Tạo, đổi tên, di chuyển, lưu trữ hoặc khôi phục một bộ sưu tập — các thư mục chứa câu hỏi, bảng điều khiển, mô hình và tài liệu.
dashboard_write	agent:content:write	Tạo hoặc cập nhật một bảng điều khiển và chỉnh sửa bố cục của nó bằng các thao tác có thứ tự.
document_write	agent:content:write	Tạo hoặc cập nhật một tài liệu.
duplicate_content	agent:content:write	Sao chép một câu hỏi, bảng điều khiển hoặc tài liệu vào một bộ sưu tập — rẻ hơn và an toàn hơn so với việc đọc bản gốc và tạo lại, đồng thời bảo toàn mọi thứ mà các phép chiếu đọc bỏ sót.
execute_query	agent:query:run	Cách mặc định để trả lời một câu hỏi từ dữ liệu: xác thực và thực thi một truy vấn có cấu trúc (MBQL), trả về các hàng cùng với một query_handle.
execute_sql	agent:sql:run	Lối thoát: thực thi một chuỗi SQL thô trên một cơ sở dữ liệu, trả về các hàng cùng với một query_handle.
get_content	agent:content:read	Tìm nạp nội dung theo {type, id} — cách đọc có kiểu cho bất kỳ thứ gì tìm thấy qua tìm kiếm hoặc browse_collection.
get_parameter_values	agent:content:read	Tìm nạp các giá trị hợp lệ cho một bộ lọc trên bảng điều khiển hoặc câu hỏi đã lưu, để bạn lọc bằng các giá trị thực thay vì đoán.
glossary	agent:content:read	Tra cứu một thuật ngữ kinh doanh theo cách phiên bản Metabase này định nghĩa; tên thuật ngữ được định nghĩa nằm trong mô tả của chính công cụ.
learn	agent:content:read	Đọc tài liệu nhiệm vụ (kỹ năng) của máy chủ này cho các phương ngữ ghi mà lược đồ không thể mô tả đầy đủ.
measure_write	agent:content:write	Tạo hoặc cập nhật một thước đo: một phép tổng hợp MBQL có tên, tái sử dụng được, gắn vào một bảng, được tham chiếu bên trong phép tổng hợp của truy vấn khác dưới dạng ["measure", id].
metric_write	agent:content:write	Tạo hoặc cập nhật một chỉ số: một phép tổng hợp đã lưu, tái sử dụng được, nằm trong một bộ sưu tập và có thể được truy vấn độc lập hoặc tham chiếu từ các truy vấn khác.
question_write	agent:content:write	Tạo, cập nhật hoặc lưu trữ một câu hỏi hoặc mô hình đã lưu.
refresh_ui_credential	agent:query:run	Làm mới thông tin xác thực có phạm vi được sử dụng bởi một Ứng dụng MCP Metabase.
render_drill_through	agent:query:run	Kết xuất trực quan hóa khoan xuống mà người dùng vừa điều hướng vào.
run_saved_question	agent:query:run	Chạy một câu hỏi đã lưu (thẻ) theo id số hoặc entity_id, trả về các hàng trực tiếp.
search	agent:content:read	Tìm nội dung trên toàn bộ phiên bản Metabase theo mức độ liên quan.
segment_write	agent:content:write	Tạo hoặc cập nhật một phân đoạn: một bộ lọc MBQL có tên, tái sử dụng được, gắn vào một bảng, được tham chiếu từ các bộ lọc của truy vấn khác.
subscription_write	agent:delivery:write	Tạo hoặc cập nhật một đăng ký bảng điều khiển — giao hàng theo lịch trình của toàn bộ bảng điều khiển, ví dụ:
visualize_query	agent:query:run	Trực quan hóa một truy vấn dưới dạng biểu đồ hoặc bảng tương tác, được kết xuất trực tiếp trong cuộc trò chuyện.

execute_query trả về row_limit hàng mỗi lần gọi (mặc định 100, tối đa 2000) — một kích thước trang, không phải là giới hạn cho kết quả. Một trang bị cắt ngắn báo cáo truncated: true và, khi truy vấn có thứ tự tổng thể, một next_cursor để truyền lại dưới dạng cursor cho trang tiếp theo, cho đến khi một trang đến với truncated: false. Một truy vấn chỉ muốn N hàng đầu tiên mang limit: N trong giai đoạn của nó (với một order-by); máy chủ tiêu giảm giới hạn đó qua các trang, vì vậy trang cuối cùng trở về đầy đủ mà không có con trỏ và phân trang tự kết thúc.

Tài nguyên

Máy chủ hiển thị các tài nguyên MCP để các máy khách có thể tìm nạp nội dung bổ sung theo URI mà không làm phình to mô tả công cụ.

URI tài nguyên	Phạm vi	Mô tả
ui://metabase/visualize-query.html	agent:query:run (chỉ thông tin xác thực UI)	Vỏ iframe của Ứng dụng MCP mà visualize_query trỏ một máy khách có khả năng đến.
ui://metabase/render-drill-through.html	agent:query:run (chỉ thông tin xác thực UI)	Vỏ mà render_drill_through trỏ đến.
catalog://metabase/fields	agent:content:read	Các đường dẫn chấm mà mỗi loại nội dung chấp nhận trong các đối số fields.

Mọi tài nguyên đều được liệt kê bất kể phạm vi của mã thông báo. Một tài nguyên dữ liệu, chẳng hạn như danh mục trường, chỉ được đọc bởi một mã thông báo giữ phạm vi của nó; nếu không, việc đọc sẽ nhận được thử thách 403 insufficient_scope được mô tả trong Phạm vi. Một vỏ UI được đọc bởi bất kỳ mã thông báo nào, vì một máy chủ MCP Apps đọc vỏ của một công cụ cùng với lệnh gọi công cụ, và nếu việc đọc đó bị từ chối, máy chủ sẽ không nâng cấp sau lệnh gọi công cụ 403. Các vỏ không mang dữ liệu. Một vỏ được đọc bởi một mã thông báo không có phạm vi của vỏ không bao giờ tạo ra thông tin xác thực UI. Dữ liệu biểu đồ được kiểm soát bởi lệnh gọi công cụ và bởi refresh_ui_credential (cả hai agent:query:run), mà iframe cần trước khi nó có thể truy vấn bất cứ điều gì. Một URI không xác định là một lỗi -32602 "Resource not found".

Các gói kỹ năng được phân phối qua công cụ learn thay vì dưới dạng tài nguyên.

Điều hướng thực thể được thực hiện bằng các công cụ get_content và browse_* thay vì một lược đồ URI; các tài nguyên ui:// ở trên chỉ tồn tại để một máy khách có thể kết xuất iframe có thứ gì đó để gắn kết.

Các phương thức JSON-RPC được hỗ trợ

Phương thức	Mô tả
initialize	Khởi tạo kết nối MCP. Trả về khả năng của máy chủ và một ID phiên.
notifications/initialized	Thông báo của máy khách rằng quá trình khởi tạo đã hoàn tất.
tools/list	Liệt kê các công cụ có sẵn, bất kể phạm vi của mã thông báo.
tools/call	Gọi một công cụ với các đối số.
resources/list	Liệt kê các tài nguyên có sẵn, bất kể phạm vi của mã thông báo.
resources/read	Đọc một tài nguyên theo URI; một tài nguyên dữ liệu cần phạm vi của nó. Yêu cầu một phiên.
ping	Ping giữ kết nối.

Các yêu cầu có thể được gửi riêng lẻ hoặc dưới dạng một lô JSON-RPC. Máy chủ phản hồi bằng JSON hoặc SSE tùy thuộc vào tiêu đề Accept.

Kiến trúc

Việc triển khai nằm trong các tệp sau:

• transport.clj - Giao thức vận chuyển HTTP. Phân tích cú pháp các yêu cầu JSON-RPC, xác thực xác thực và tiêu đề phiên, thực thi kiểm tra nguồn gốc (bảo vệ chống rebinding DNS) và điều phối đến phương thức thích hợp. Hỗ trợ cả định dạng phản hồi JSON và SSE.

• v2/api.clj - Trình xử lý bề mặt công cụ. Kết nối giao thức vận chuyển với các đăng ký công cụ + tài nguyên v2 và định nghĩa điều phối phương thức (tools/list, tools/call, resources/list, resources/read, ping).

• v2/registry.clj - Đăng ký công cụ v2. Các công cụ tự đăng ký qua deftool; đăng ký kiểm tra phạm vi, xác thực đối số, điều phối lệnh gọi và ghi lại việc sử dụng.

• scope.clj - Logic khớp phạm vi. Chỉ khớp chính xác: ký tự đại diện, phạm vi nil và sentinel ::unrestricted không khớp với bất cứ điều gì.

Luồng yêu cầu

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Đọc thêm

• Tài liệu người dùng MCP
• Mã nguồn Agent API
• Đặc tả Giao thức Ngữ cảnh Mô hình