FinancialMD cho AI agent
FinancialMD là terminal tài chính được xây dựng cho AI agent. Nó cung cấp các báo cáo tài chính được xây dựng từ hồ sơ nộp SEC. Mọi con số đều đi kèm bằng chứng truy ngược về hồ sơ nộp SEC, và mọi lượt đọc đều có thể thực hiện tại một ngày trong quá khứ, để agent có thể trích dẫn điều mình nói và backtest mà không bị look-ahead.
Bước 1. Kết nối máy chủ MCP
Máy chủ MCP ở https://mcp.financial.md/mcp (Streamable HTTP, không trạng thái). Nó có 57 công cụ chỉ đọc. Đăng nhập là tùy chọn: không có token, nó trả lời trong giới hạn hằng ngày không cần key.
Claude Code:
claude mcp add --transport http financial-md https://mcp.financial.md/mcpCác ứng dụng khách đọc cấu hình JSON (Cursor, VS Code, Windsurf và các ứng dụng khác):
{
"mcpServers": {
"financial-md": { "type": "http", "url": "https://mcp.financial.md/mcp" }
}
}Trong Claude hoặc ChatGPT, thêm cùng URL đó làm connector tùy chỉnh. Thẻ máy chủ ở mcp.financial.md/.well-known/mcp.json và metadata OAuth ở mcp.financial.md/.well-known/oauth-protected-resource.
Bắt đầu với company_lookup, sau đó snapshot_as_of (cả ba báo cáo tài chính và các tỷ lệ như được biết tại một ngày, trong một lệnh gọi) hoặc financials_standardized. Dùng verify_value để kiểm tra một con số bạn tìm thấy ở nơi khác.
Bước 2. Thực hiện cuộc gọi API không cần chìa khóa
HTTP API không cần tài khoản và không cần chìa khóa. Cuộc gọi này trả về năm báo cáo lưu chuyển tiền tệ hàng năm gần nhất của Apple, bao gồm cả dòng tiền tự do:
curl "https://api.financial.md/v1/company/financials/cash_flow/standardized?company=ticker:AAPL&period_type=annual&limit=5"Mỗi con số là một value object với proof.accession, proof.form, proof.filed và proof.source_url (hồ sơ nộp SEC trên sec.gov). Thêm as_of=2024-06-30 để đọc những gì được biết vào ngày đó. Đối chiếu một con số với hồ sơ nộp SEC:
curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
-d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'Không có key, mỗi địa chỉ IP có 10 lượt gọi theo hạn mức mỗi ngày (ratios, screen, verify), 1,000 lượt đọc ở lớp hồ sơ nộp SEC và 1,000 lượt đọc metadata. Mọi phản hồi đều có header RateLimit-*; phản hồi 429 có Retry-After, và mọi nội dung lỗi đều liệt kê cách khắc phục.
Bước 3. Trả tiền theo lượt gọi
agent.financial.md phục vụ các route tương tự cho agent trả tiền theo lượt gọi bằng x402 (USDC trên Base), không cần tài khoản. Một route có giá ở đó sẽ trả về 402 với giá trong header PAYMENT-REQUIRED; ký thanh toán và gửi lại lượt gọi với header PAYMENT-SIGNATURE. Nội dung của phản hồi 402 cũng nêu host không cần key, nơi cùng route đó không bao giờ bị tính phí trong giới hạn hằng ngày.
Giá của mỗi route được ghi trong pricing.json và trong trường x-price của tài liệu OpenAPI. Giá trong phản hồi 402 là giá áp dụng. Lượt gọi thất bại sẽ không bị tính phí.
Tệp cho agent
| Tệp | Mô tả |
|---|---|
| openapi.json | OpenAPI 3.1. Mỗi operation đều có mô tả và một yêu cầu ví dụ với mã chứng khoán thực tế |
| llms.txt | Hướng dẫn ngắn: host, id công ty, value object, lượt đọc tại một thời điểm (point-in-time), giới hạn |
| llms-full.txt | Tất cả trong một tệp văn bản: mọi route, công thức tỷ số và cách làm |
| skill.md | Agent Skill với các cách làm chỉ cần một lượt gọi |
| skills.zip | Các Agent Skill (SKILL.md) gọi công cụ MCP, gộp trong một tệp zip |
| pricing.json | Giá theo lượt gọi, giới hạn hằng ngày và trạng thái thanh toán |
| mcp.json | Thẻ máy chủ MCP: công cụ, xác thực và tài liệu |
| server.json | Mục trong MCP Registry |
| agent.json | Một chỉ mục của mọi endpoint và tài liệu ở trên |
Những gì agent có thể dựa vào
- Mọi con số đều có nguồn: accession number của hồ sơ nộp SEC, form, ngày nộp hồ sơ, thẻ XBRL và một liên kết tới tài liệu trên sec.gov.
GET /proof/{id}hiển thị các dữ kiện thô đằng sau nó. - Tại một thời điểm:
known.fromvàknown.tocho biết khi nào mỗi giá trị là số liệu được nộp mới nhất.as_of,original=truevàhistory=trueđọc dữ liệu quá khứ mà không nhìn trước và hiển thị các số liệu trình bày lại. - Câu trả lời ngắn: một lượt gọi báo cáo chỉ trả về các kỳ được yêu cầu; kết quả công cụ MCP bắt đầu bằng bản tóm tắt một dòng trước dữ liệu có cấu trúc.
- Mã chứng khoán, CIK hoặc tên:
company=ticker:AAPL,company=cik:320193, hoặcGET /v1/companies?q=Apple. - Phạm vi bao phủ: các đơn vị nộp hồ sơ SEC hiện được niêm yết trên một sàn giao dịch ở US; báo cáo chuẩn hóa cho các đơn vị nộp theo US GAAP. Chỉ cung cấp thông tin, không phải tư vấn đầu tư.