KOPA Docs›MCP — hướng dẫn chi tiết

MCP — hướng dẫn chi tiết

Setup KOPA MCP server với Claude Desktop, Cursor, ChatGPT, custom agent — danh sách tools đầy đủ, ví dụ prompt, security model, rate limit.

MCP — hướng dẫn chi tiết

MCP (Model Context Protocol) là chuẩn mở do Anthropic công bố, cho phép AI agent kết nối tool bên ngoài. KOPA xuất bản MCP server read-only để agent bên thứ ba truy vấn dữ liệu kế toán — phù hợp khi bạn dùng Claude Desktop, Cursor, ChatGPT, hoặc tự xây agent.

Trang này đi sâu hơn so với API & MCP — tổng quan.

Tóm tắt nhanh#

Endpoint: https://mcp.getkopa.com/mcp
Transport: Streamable HTTP (chuẩn MCP 2025).
Auth: Bearer token.
Capabilities: tools (read-only), không có resources / prompts / sampling.
Server card: https://docs.getkopa.com/.well-known/mcp/server-card.json

Vì sao dùng MCP của KOPA#

Có 3 use case chính:

1. Hỏi Claude/ChatGPT về data kế toán#

Thay vì mở KOPA → mở module → search → đọc, bạn hỏi thẳng AI:

"Theo KOPA, doanh thu tháng 4 của Sao Mai bao nhiêu? So với tháng 3?"

Claude tự gọi tool MCP, trả lời:

"Theo dữ liệu KOPA: doanh thu T04/2024 đạt 2.5 tỉ VND, tăng 8% so với T03 (2.3 tỉ). Tăng chủ yếu nhờ 3 khách hàng mới (+200tr) và mix sản phẩm cao hơn..."

2. Xây agent doanh nghiệp tùy biến#

Doanh nghiệp có quy trình đặc thù muốn build agent riêng:

Pipeline báo cáo khách hàng tự động.
Chatbot Slack trả lời câu hỏi tài chính nội bộ.
Tích hợp KOPA data với BI tool (Tableau, Looker).

MCP cho bạn kết nối bất kỳ AI agent nào với KOPA mà không cần REST API custom.

3. Workflow phức hợp với context KOPA#

Một agent có thể vừa đọc KOPA, vừa viết Notion, vừa gửi Slack — MCP hợp các tool source khác nhau lại.

Setup token#

Trước khi cấu hình client, cần có API token:

Đăng nhập KOPA web.
Cài đặt → Tài khoản → API tokens → + Tạo token mới.
Đặt tên (vd "Personal MCP token Mai").
Chọn scope:
- read:reports — đọc báo cáo.
- read:journal_entries — đọc bút toán.
- read:banking — đọc giao dịch ngân hàng.
- read:documents — đọc chứng từ.
- read:kpi — đọc KPI.
- read:all — full read-only.
KOPA hiển thị token một lần — copy ngay.

kopa_pat_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Bảo mật: Treat token như mật khẩu. Lưu trong password manager. Không commit vào Git. Revoke ngay khi nghi ngờ leak.

Setup với Claude Desktop#

Bước 1 — Mở config#

OS	File
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Bước 2 — Thêm KOPA server#

{
  "mcpServers": {
    "kopa": {
      "url": "https://mcp.getkopa.com/mcp",
      "headers": {
        "Authorization": "Bearer kopa_pat_xxxx"
      }
    }
  }
}

Bước 3 — Restart Claude Desktop#

Quit hoàn toàn (Cmd+Q) rồi mở lại. Trong UI, bấm icon 🔌 dưới khung chat — bạn sẽ thấy kopa với danh sách tool.

Bước 4 — Thử#

Hỏi:

"Dùng KOPA, cho tôi xem balance sheet công ty Sao Mai tháng 4."

Claude sẽ gọi tool getBalanceSheet, trả về JSON, format thành bảng đẹp cho bạn.

Setup với Cursor#

Bước 1 — Mở config#

~/.cursor/mcp.json

Bước 2 — Cấu hình#

Cùng format Claude Desktop:

{
  "mcpServers": {
    "kopa": {
      "url": "https://mcp.getkopa.com/mcp",
      "headers": {
        "Authorization": "Bearer kopa_pat_xxxx"
      }
    }
  }
}

Bước 3 — Restart Cursor#

Cmd+Shift+P → "Reload Window".

Bước 4 — Dùng#

Trong Cursor chat, gõ @kopa để invoke server. Hữu ích khi đang code tích hợp với KOPA.

Setup với ChatGPT (Custom GPT)#

ChatGPT chưa hỗ trợ MCP native (tới Q2 2026 OpenAI vẫn đang work on). Workaround:

Cách 1 — Custom GPT với Action#

Tạo Custom GPT trong ChatGPT.
Configure → Actions → + Create new action.
Schema OpenAPI từ KOPA: https://api.getkopa.com/openapi.json.
Authentication: API Key → Authorization: Bearer kopa_pat_xxxx.
Save → test.

Đây không phải MCP nhưng tương đương về function — Custom GPT có thể gọi REST API KOPA.

Cách 2 — MCP gateway#

Có open-source MCP-to-OpenAI gateway như mcp-gateway. Setup gateway local, ChatGPT call OpenAPI của gateway, gateway forward tới MCP. Phức tạp, ít người dùng.

KOPA team đang theo dõi roadmap OpenAI — sẽ cập nhật khi ChatGPT support MCP native.

Setup với agent tự build#

Python#

pip install mcp-client

from mcp_client import StreamableHTTPClient

async with StreamableHTTPClient(
    url="https://mcp.getkopa.com/mcp",
    headers={"Authorization": "Bearer kopa_pat_xxxx"}
) as client:
    tools = await client.list_tools()
    print(f"KOPA exposes {len(tools)} tools")
    
    # Call a tool
    result = await client.call_tool(
        "getBalanceSheet",
        {"companyId": "co_saomai", "period": "2024-04"}
    )
    print(result)

TypeScript / Node#

npm install @modelcontextprotocol/sdk

import { StreamableHTTPClient } from "@modelcontextprotocol/sdk/client/streamable-http";

const client = new StreamableHTTPClient({
  url: "https://mcp.getkopa.com/mcp",
  headers: { Authorization: `Bearer ${process.env.KOPA_PAT}` },
});

await client.connect();
const tools = await client.listTools();
const result = await client.callTool("getRunway", { companyId: "co_saomai" });

Danh sách tool đầy đủ#

KOPA MCP expose 24 tool read-only chia 6 nhóm:

Master data#

Tool	Description	Example call
`getCompanies`	List công ty trong workspace	`{}`
`getCompany`	Chi tiết một công ty	`{"id": "co_xxx"}`
`getChartOfAccounts`	Hệ thống tài khoản	`{"companyId": "co_xxx"}`
`getCustomers`	Danh sách khách hàng	`{"companyId": "co_xxx", "limit": 100}`
`getSuppliers`	Danh sách nhà cung cấp	Same
`getEmployees`	Danh sách nhân viên	Same

Sổ kế toán#

Tool	Description
`getJournalEntries`	Bút toán theo filter (kỳ, tài khoản, đối tượng)
`getJournalEntry`	Chi tiết một bút toán
`getAccountBalance`	Số dư tài khoản tại thời điểm
`getGeneralLedger`	Sổ cái chi tiết

Báo cáo tài chính#

Tool	Description
`getBalanceSheet`	Bảng cân đối kế toán
`getPLStatement`	Báo cáo kết quả kinh doanh
`getCashFlowStatement`	Lưu chuyển tiền tệ
`getTrialBalance`	Bảng cân đối phát sinh

Banking#

Tool	Description
`getBankAccounts`	List tài khoản ngân hàng
`getBankBalance`	Số dư hiện tại
`getBankTransactions`	Giao dịch theo filter
`getCashForecast`	Dự báo dòng tiền

Tài liệu & Hóa đơn#

Tool	Description
`searchDocuments`	Search chứng từ
`getInvoices`	Hóa đơn (đầu vào / đầu ra)
`getDocument`	Chi tiết một chứng từ

Phân tích#

Tool	Description
`getKPI`	Giá trị KPI
`getRunway`	Runway tháng
`getAlerts`	Active alerts
`runReport`	Sinh báo cáo theo template

Filter/pagination#

Mọi tool list (getJournalEntries, getBankTransactions, ...) hỗ trợ:

companyId — bắt buộc nếu workspace nhiều công ty.
period — "2024-04" cho tháng 4, "Q2-2024" cho quý.
from / to — ISO date range.
limit — mặc định 100, max 1000.
cursor — pagination cursor cho lần gọi tiếp.

Response format:

{
  "items": [...],
  "totalCount": 1234,
  "nextCursor": "eyJpZCI6..."
}

Ví dụ prompt thực tế#

"Phân tích biến động lợi nhuận"#

"Dùng KOPA, lấy P&L Sao Mai T03 và T04. Phân tích vì sao biên lợi nhuận gộp giảm 2pp."

Claude sẽ:

Call getPLStatement cho T03.
Call getPLStatement cho T04.
So sánh, tính delta.
Call getJournalEntries filter giá vốn, top 10.
Phân tích: "Giảm 2pp do (a) chi phí nguyên vật liệu tăng 5% — driver chính, hóa đơn từ NCC ABC giá tăng 8% (b) chi phí thuê nhà xưởng tăng theo CPI 3.5%."

"Email nhắc khách quá hạn"#

"Lấy AR aging Sao Mai cuối T04. Soạn email tiếng Việt nhắc nhở thanh toán cho khách hàng quá hạn > 60 ngày, lịch sự, kèm bảng nợ chi tiết."

Claude:

Call getKPI với name="ar_aging".
Filter aging > 60.
Soạn email cho từng khách (4 email khác nhau) — tone phù hợp.
Trả lại 4 email cho bạn review.

"Cash forecast cuộc họp board"#

"Cho cuộc họp board T05, tôi cần: cash position cuối T04, runway hiện tại, dự báo 6 tháng tới base case, và 3 risk factor lớn nhất."

Claude tổng hợp từ getBankBalance, getRunway, getCashForecast, getAlerts — gói thành slide 1-pager.

Security model#

Permissions inherit từ user#

Token chỉ có thể truy cập những gì user (chủ token) có quyền. Ví dụ:

User là Reviewer → token chỉ đọc, không write (đã enforced bằng read-only design).
User scope = "Sao Mai" → token không truy cập "ABC Co" trong cùng workspace.

IP allowlist (Enterprise)#

Workspace Enterprise có thể giới hạn token chỉ dùng được từ IP cụ thể.

Cấu hình tại Cài đặt → API tokens → IP allowlist.

Audit log đầy đủ#

Mọi MCP call ghi vào audit log:

Token ID (không hiện token thật).
Tool name.
Input.
Output size.
Latency.
Success / error.
IP request từ.

Xem tại Cài đặt → Audit log → Filter channel=mcp.

Token rotation#

Khuyến nghị:

Cá nhân: rotate mỗi 6 tháng.
Production agent: rotate mỗi 90 ngày.
KOPA gửi email nhắc rotate khi gần hết hạn (nếu set TTL).

Rate limits#

Plan	Requests/phút	Concurrent connections
Starter	30	2
Growth	300	10
Enterprise	3,000	100

Header response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1714128000

Vượt → HTTP 429, retry sau giây trong header Retry-After.

Streaming responses#

Một số tool trả về stream cho phản hồi nhanh hơn:

runReport — stream từng section của báo cáo.
getCashFlowStatement — stream từng nhóm hoạt động.

Client MCP chuẩn handle stream tự động. Streaming không thay đổi rate limit (1 stream = 1 request).

Discovery#

KOPA tuân thủ MCP discovery RFC:

Server card: https://docs.getkopa.com/.well-known/mcp/server-card.json
API catalog: https://docs.getkopa.com/.well-known/api-catalog
OAuth metadata: https://docs.getkopa.com/.well-known/oauth-protected-resource

Agent có thể tự động discover KOPA và lên kế hoạch kết nối.

Khác biệt MCP vs REST API KOPA#

	MCP	REST API
Đối tượng	AI agent	Bất kỳ HTTP client
Schema	Tool calling format	OpenAPI 3.1
Streaming	✅ Built-in	⚠ SSE optional
Auto-discovery	✅ Standard	❌ Phải đọc spec
Best for	Agentic workflows	Backend integrations

Khi nào dùng MCP, khi nào REST?

Agent → MCP.

App backend / cron → REST.

Roadmap#

Q3 2026 — write tools (proposeJournalEntry, sendNotification) sau khi có MCP write spec ổn định.
Q3 2026 — resources capability — expose chứng từ làm MCP resources.
Q4 2026 — prompts capability — KOPA prompt template marketplace.

Sự cố thường gặp#

Connection refused / 401#

Token sai hoặc đã revoke.
Header format không đúng — phải là Authorization: Bearer xxx.

Tool không thấy#

Tool yêu cầu scope mà token không có. Tạo token mới với scope phù hợp.

Rate limited liên tục#

Upgrade plan.
Cache result phía client (KOPA data thường không thay đổi nhanh).

Latency cao#

Production: KOPA tự deploy edge (< 100ms cho VN).
Self-host: chọn region gần user.

Tiếp theo#

API & MCP — tổng quan — REST API và OpenAPI.
Skills & MCP — quản lý MCP server từ trong KOPA.

Bài trước

← API & MCP — tổng quan