Tài liệu dành cho nhà phát triển

MCP

Kết nối Claude, Codex và các MCP client khác với ghi chú Alt của bạn.

Alt cung cấp máy chủ MCP (Model Context Protocol) được lưu trữ sẵn. Client hỗ trợ OAuth có thể đăng nhập trên trình duyệt; API key vẫn là phương án dự phòng. Cả hai cách đều áp dụng cùng scope chỉ đọc và ranh giới workspace.

Bắt đầu tại đây

Chạy trình hướng dẫn tương tác trong thư mục dự án. Công cụ sẽ hướng dẫn kết nối MCP, kiểm tra khóa API và webhook, rồi bàn giao phần triển khai cho tác nhân lập trình.

npx

npx altalt --mcp-only

1. Kết nối bằng OAuth (khuyên dùng)

Chỉ thêm endpoint, không thêm header. Client sẽ tìm máy chủ ủy quyền của Alt, tự đăng ký và mở màn hình đồng ý trong trình duyệt.

Alt hỗ trợ Dynamic Client Registration và PKCE, vì vậy client tương thích tự động cấu hình OAuth.
Kiểm tra các scope chỉ đọc và workspace được yêu cầu trong trình duyệt trước khi phê duyệt quyền truy cập.
OAuth hiện chỉ dành cho quản trị viên Alt. Nếu kết nối OAuth Alt cũ không còn xác thực sau nâng cấp này, hãy xóa khỏi client rồi thêm lại một lần.

2. Kết nối client của bạn

Dùng cấu hình chỉ có URL cho OAuth. Không cần OAuth client ID hay secret; chỉ dùng API key khi client không thể hoàn tất OAuth.

MCP URL

https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

Mở Customize → Connectors → Add custom connector, nhập endpoint ở trên, để trống OAuth client ID và secret, rồi chọn Connect.

Claude Code

shell

claude mcp add --transport http alt https://mcp.altalt.io/mcp

Sau khi thêm server, mở /mcp trong Claude Code, chọn Alt và hoàn tất xác thực trên trình duyệt.

Codex CLI

shell

codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt

config.toml

# ~/.codex/config.toml
[mcp_servers.alt]
url = "https://mcp.altalt.io/mcp"

Việc thêm server thường sẽ hoàn tất luôn xác thực trên trình duyệt. Nếu xác thực không bắt đầu, hãy chạy codex mcp login alt.

Cursor

Thêm vào Cursor

Cài đặt một chạm chỉ với URL. Trong cài đặt MCP của Cursor, chọn Connect hoặc Needs authentication rồi phê duyệt màn hình đồng ý trên trình duyệt.

Client khác và phương án API key

Bắt đầu với cấu hình OAuth chỉ có URL. Nếu client không hỗ trợ MCP OAuth, hãy dùng cấu hình API key Bearer.

OAuth

{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp"
    }
  }
}

API key

{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp",
      "headers": { "Authorization": "Bearer alt_live_..." }
    }
  }
}

API key vẫn được hỗ trợ cho tự động hóa và client cũ. Tạo key trong bảng điều khiển tài khoản, chỉ cấp scope cần thiết, không lưu trong cấu hình dùng chung và xem Bảo mật để quản lý key.

3. Công cụ

Bốn công cụ chỉ đọc, phản chiếu REST API và áp dụng cùng các scope.

list_notes — Liệt kê các ghi chú mà key thấy được, với phân trang con trỏ và bộ lọc updated_after (notes:read).
get_note — Lấy metadata của một ghi chú: tiêu đề, trạng thái bản ghi chép/tóm tắt, dấu thời gian (notes:read).
get_note_transcript — Lấy toàn bộ bản ghi chép dưới dạng các đoạn có thời gian và nhãn người nói (transcripts:read).
get_note_summary — Lấy bản tóm tắt AI dưới dạng Markdown (summaries:read).

Ghi chú xuất hiện khi bản ghi âm kết thúc hoặc bản tóm tắt được tạo — ghi chú chỉ có memo sẽ không được xuất. Trước khi nội dung sẵn sàng, công cụ trả về transcript_not_ready / summary_not_ready để agent biết thử lại sau.