OpenCode là một AI coding agent CLI mã nguồn mở, chạy trực tiếp trong terminal và có thể mở rộng khả năng thông qua MCP (Model Context Protocol) — chuẩn giao tiếp cho phép agent gọi các "tool" bên ngoài một cách có kiểm soát. Khi bạn gắn một Jira MCP server vào OpenCode, agent không còn chỉ đọc/viết code trong repo mà còn có thể tra cứu issue, cập nhật trạng thái, bình luận, và tổng hợp dữ liệu sprint ngay trong phiên làm việc — không cần mở tab browser sang Jira. Bài này đi thẳng vào phần thực chiến: cấu hình MCP server trong opencode.json, các prompt mẫu để truy vấn/cập nhật issue và sprint, một ví dụ đầy đủ về lập kế hoạch sprint, và những hạn chế bạn cần biết trước khi giao việc thật cho agent.
Cài đặt và Kết nối Jira MCP vào OpenCode
Có hai hướng phổ biến để có một Jira MCP server dùng được với OpenCode: dùng Atlassian Remote MCP Server chính chủ (chạy trên cloud của Atlassian, xác thực qua OAuth), hoặc self-host một server community như mcp-atlassian (gói Python nổi tiếng của sooperset, giao tiếp qua API token/PAT). Cả hai đều expose issue, project, sprint dưới dạng tool mà agent gọi được — khác nhau chủ yếu ở cách xác thực và mức độ kiểm soát bạn có với server.
Chọn remote server hay self-host
Remote MCP (OAuth) tiện vì không cần quản lý credential dài hạn, phù hợp máy cá nhân, ít rủi ro leak token khi commit nhầm file config. Self-host bằng mcp-atlassian phù hợp khi công ty dùng Jira Server/Data Center (on-prem, không hỗ trợ OAuth cloud), hoặc khi bạn muốn kiểm soát chặt hơn — ví dụ chạy trong Docker container riêng cho từng project, giới hạn scope theo project key.
Mẹo: Nếu team đang dùng Jira Cloud và chỉ cần cấp quyền cho cá nhân, ưu tiên Remote MCP OAuth trước — ít việc bảo trì hơn hẳn so với tự host, và bạn tránh được việc phải xoay API token mỗi khi nó hết hạn hoặc bị revoke.
Lấy credential cần thiết
Với mcp-atlassian self-host, bạn cần một API token (Atlassian ID → Security → API tokens) và email tài khoản Jira. Với Jira Server/Data Center, dùng Personal Access Token (PAT) thay cho email + API token. Lưu các giá trị này vào biến môi trường cục bộ, tuyệt đối không hardcode vào file opencode.json sẽ commit lên git:
export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="you@company.com"
export JIRA_API_TOKEN="ATxxxxxxxxxxxxxxxxxxxxxxxxxx"
Khai báo MCP server trong opencode.json
OpenCode đọc cấu hình MCP từ opencode.json ở root project hoặc ở ~/.config/opencode/opencode.json cho cấu hình global. Cấu hình cho server self-host chạy qua uvx (tool runner của Python uv):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jira": {
"type": "local",
"command": ["uvx", "mcp-atlassian"],
"environment": {
"JIRA_URL": "https://your-domain.atlassian.net",
"JIRA_USERNAME": "you@company.com",
"JIRA_API_TOKEN": "{env:JIRA_API_TOKEN}"
},
"enabled": true
}
}
}
Nếu dùng Atlassian Remote MCP Server (SSE, OAuth), khai báo dạng remote:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jira-remote": {
"type": "remote",
"url": "https://mcp.atlassian.com/v1/sse",
"enabled": true
}
}
}
Với server remote, lần đầu chạy OpenCode sẽ mở luồng OAuth trong browser để bạn login và cấp quyền — sau đó token được lưu cục bộ và tự refresh, bạn không cần khai báo environment gì thêm.
Kiểm tra kết nối
Chạy OpenCode và gõ lệnh kiểm tra danh sách MCP server đang active:
opencode
/mcp
Nếu server jira hiện trạng thái connected và danh sách tool (jira_search, jira_get_issue, jira_create_issue, jira_transition_issue, ...) hiện ra là đã kết nối thành công. Nếu báo lỗi timeout, kiểm tra lại JIRA_URL không có dấu / thừa ở cuối, và tài khoản API token còn hiệu lực.
Truy vấn và Cập nhật Issue và Sprint từ OpenCode
Sau khi kết nối, agent trong OpenCode có quyền gọi các tool mà Jira MCP expose. Tên tool cụ thể tùy server, nhưng nhóm chức năng thường gồm: tìm kiếm issue bằng JQL, lấy chi tiết một issue, tạo issue mới, chuyển trạng thái (transition), thêm comment, và các tool liên quan sprint/board (lấy sprint hiện tại, thêm/xóa issue khỏi sprint, lấy backlog).
Truy vấn issue bằng ngôn ngữ tự nhiên (agent tự dịch sang JQL)
Bạn không cần nhớ cú pháp JQL — cứ mô tả bằng tiếng Việt hoặc tiếng Anh, agent sẽ tự chọn tool và tham số phù hợp:
Tìm tất cả issue trong project "PLAT" đang ở trạng thái "In Progress",
được assign cho tôi, và có priority từ Medium trở lên. Liệt kê kèm sprint hiện tại.
Agent thường sẽ gọi tool search với JQL tương đương project = PLAT AND status = "In Progress" AND assignee = currentUser() AND priority in (Medium, High, Highest), rồi format lại kết quả thành bảng dễ đọc trong terminal.
Cập nhật trạng thái và comment
Chuyển issue PLAT-482 sang "In Review", và thêm comment:
"Đã push code, PR: github.com/org/repo/pull/213. Cần review trước 5h chiều."
Agent sẽ gọi jira_get_issue trước để lấy danh sách transition hợp lệ (tránh gọi sai transition ID gây lỗi), sau đó gọi jira_transition_issue rồi jira_add_comment. Đây là điểm bạn nên biết: agent chạy nhiều tool call nối tiếp trong một lượt trả lời — hữu ích nhưng cũng là nơi dễ xảy ra thao tác ngoài ý muốn nếu bạn ra lệnh mơ hồ.
Làm việc với sprint
Sprint hiện tại của board "PLAT Sprint Board" có bao nhiêu issue chưa estimate?
Liệt kê issue key, summary, và assignee.
hoặc để thêm issue vào sprint đang mở:
Thêm issue PLAT-501 và PLAT-502 vào sprint đang active của board PLAT.
Mẹo: Khi ra lệnh cập nhật (transition, add-to-sprint, close issue), luôn chỉ định rõ issue key cụ thể (PLAT-482) thay vì mô tả mơ hồ ("issue tôi vừa nói"). Agent có context window hạn chế và có thể nhớ nhầm issue key từ câu trước, dẫn đến update sai issue — rất khó phát hiện ngay vì Jira không rollback tự động.
Ví dụ Thực tế: Đề xuất Lập kế hoạch Sprint trong OpenCode
Đây là kịch bản thực dùng hàng tuần của nhiều team: trước buổi sprint planning, bạn muốn có sẵn một bản đề xuất — issue nào nên vào sprint tới, dựa trên velocity trung bình, priority, và các issue đang bị block.
Prompt đầy đủ
Tôi cần chuẩn bị sprint planning cho team PLAT. Hãy:
1. Lấy velocity trung bình của 3 sprint gần nhất (tổng story points completed).
2. Lấy toàn bộ backlog của board PLAT Sprint Board, sắp theo priority giảm dần.
3. Loại các issue đang bị block (có label "blocked" hoặc còn issue link
type "is blocked by" chưa resolve).
4. Đề xuất danh sách issue cho sprint tới sao cho tổng story points xấp xỉ
velocity trung bình, ưu tiên issue priority cao và đã có estimate.
5. Với issue chưa có estimate nhưng priority cao, gắn cờ riêng để team estimate
trong buổi refinement.
Trình bày kết quả dạng bảng: Issue key | Summary | Story points | Priority | Ghi chú.
Agent sẽ hành xử như thế nào
OpenCode sẽ chia việc này thành một chuỗi tool call: gọi search JQL cho 3 sprint đã đóng để lấy story points completed (thường cần gọi riêng cho từng sprint vì JQL không tổng hợp sẵn), tính trung bình trong phần suy luận của chính agent (không phải Jira tính), gọi tiếp search backlog với JQL dạng project = PLAT AND sprint is EMPTY AND status != Done ORDER BY priority DESC, sau đó lọc thủ công các issue có label "blocked" hoặc issue link chưa resolve — bước lọc này agent phải tự đọc field issuelinks trả về, không có tool nào làm sẵn việc "loại blocked issue".
Kết quả trả về là một bảng gợi ý — bạn nên coi đây là điểm khởi đầu cho buổi họp, không phải quyết định cuối. Agent không biết context ngoài Jira: ai đang nghỉ phép, dependency với team khác chưa được ghi trong issue, độ phức tạp thực tế của story point cũ có đúng không.
Áp dụng kết quả
Nếu đồng ý với đề xuất, bạn có thể yêu cầu ngay:
Thêm 8 issue đầu tiên trong bảng trên vào sprint mới "Sprint 24" của board PLAT.
Với 2 issue chưa có estimate, thêm comment nhắc "Cần estimate trong refinement"
và gắn label "needs-estimate".
Agent thực thi luôn các transition/update này bằng đúng tool đã dùng ở phần trước — đây chính là giá trị thực của MCP: bạn không cần copy-paste qua lại giữa AI chat và Jira UI, toàn bộ vòng lặp "phân tích → hành động" nằm trong một phiên OpenCode.
Mẹo: Luôn yêu cầu agent trình bày đề xuất trước, chờ bạn duyệt, rồi mới ra lệnh apply riêng ở bước sau (như ví dụ trên) — tách rõ "read" và "write". Đừng gộp chung một prompt "phân tích và tự động thêm vào sprint luôn", vì bạn sẽ mất bước kiểm tra trước khi dữ liệu Jira thật bị thay đổi.
Hạn chế Đã biết của Jira MCP trong OpenCode
Dù tiện, Jira MCP trong OpenCode có một số giới hạn thực tế cần lưu ý trước khi đưa vào workflow chính thức của team.
Giới hạn JQL và phân trang (pagination)
Hầu hết Jira MCP server giới hạn số issue trả về mỗi lần gọi (thường 50–100 issue/page). Với backlog lớn hàng trăm issue, agent phải gọi tool nhiều lần để lấy hết dữ liệu, tốn thời gian và có thể vượt giới hạn context window nếu bạn yêu cầu xử lý toàn bộ project cùng lúc — agent sẽ tự cắt bớt hoặc tóm tắt, dễ bỏ sót issue mà bạn không biết.
Không có khái niệm "board" đầy đủ như UI Jira
Nhiều Jira MCP server chỉ expose issue/sprint/project qua REST API, không mô phỏng đầy đủ board (Kanban swimlane, board filter tùy chỉnh, quick filter). Nếu team có board với JQL filter phức tạp cấu hình riêng, agent không "nhìn thấy" board đó theo đúng nghĩa UI — nó chỉ thấy được sprint và issue thô, bạn phải tự dịch lại logic filter đó thành JQL trong prompt.
Quyền hạn đi theo credential, không có review step tích hợp
Agent hành động với đúng quyền của API token/OAuth bạn cấp — không có lớp "approval" trung gian như pull request review trong Git. Một prompt viết ẩu ("dọn hết issue cũ trong backlog") có thể khiến agent transition/close nhầm issue đang cần giữ. Jira có audit log nên truy ngược được, nhưng không có "undo" một lệnh transition hàng loạt.
Đồng bộ dữ liệu không real-time hai chiều
OpenCode chỉ đọc/viết Jira khi bạn chủ động ra lệnh trong phiên đó — không có subscription/webhook để agent tự biết issue vừa được người khác cập nhật. Nếu bạn mở phiên OpenCode buổi sáng và làm việc suốt ngày, dữ liệu sprint/issue trong context của agent có thể lệch với thực tế nếu đồng nghiệp cập nhật Jira song song; nên yêu cầu agent "refresh" (gọi lại jira_get_issue) trước khi ra quyết định quan trọng.
Mẹo: Với các thao tác ảnh hưởng nhiều issue cùng lúc (bulk transition, bulk add-to-sprint), luôn yêu cầu agent liệt kê danh sách issue key sẽ bị tác động và chờ bạn xác nhận "OK" bằng văn bản trước khi cho gọi tool ghi (write). Coi đây như một "dry-run" thủ công, bù cho việc MCP hiện chưa có review step tích hợp.
Mẹo hay
Tổng hợp lại, để dùng Jira MCP với OpenCode hiệu quả và an toàn trong công việc hàng ngày:
- Tách biệt token: dùng một API token/PAT riêng cho mục đích MCP, không dùng chung token cá nhân bạn đang dùng cho tích hợp khác — dễ revoke khi cần mà không ảnh hưởng việc khác.
- Bắt đầu với quyền đọc trước: nếu Jira instance hỗ trợ, thử nghiệm với một service account chỉ có quyền read trên vài project để làm quen hành vi agent, trước khi cấp quyền write toàn diện.
- Luôn chỉ định rõ project key/board name trong prompt, tránh để agent tự đoán project khi bạn làm việc với nhiều project song song trong cùng phiên.
- Định kỳ review lại danh sách tool mà MCP server expose (qua
/mcptrong OpenCode) sau mỗi lần upgrade server — tool mới có thể thêm quyền bạn chưa lường tới.
Mẹo: Ghi lại thành một file "Jira MCP prompt playbook" trong repo của team (ví dụ
docs/jira-mcp-prompts.md) với các prompt mẫu đã kiểm chứng cho từng tác vụ lặp lại — tra cứu issue, chuẩn bị sprint planning, đóng sprint. Việc này giúp cả team dùng chung cách ra lệnh nhất quán, giảm rủi ro prompt mơ hồ dẫn tới thao tác sai trên dữ liệu Jira thật.