MCP 연동

Model Context Protocol로 AI 코딩 어시스턴트가 내 Velocis 워크스페이스에서 작업하게 하세요.

자연어로 Velocis에 말 걸기

Velocis MCP 서버는 AI 에디터(Claude Desktop, Cursor, Antigravity 등)가 대신 60개의 Velocis 도구를 호출하게 해줍니다. 권한은 서버에서 본인의 프로젝트 멤버십 기준으로 다시 검증되므로, 도구도 본인이 볼 수 있는 것 이상은 볼 수 없습니다.

VEL 프로젝트에 로그인 버그 이슈 등록해줘
VEL-101 상태를 in_progress로 바꾸고 나한테 할당해줘
이번 주 내 작업량을 이슈별로 정리해줘

시작하기

프로필 → 통합 설정 → 액세스 토큰에서 개인 액세스 토큰을 발급한 뒤, MCP 클라이언트 환경에 VELOCIS_ACCESS_TOKEN으로 설정하세요 (아래 환경 변수 참고).

환경 변수

변수	설명	기본값
`VELOCIS_ACCESS_TOKEN`필수	개인 액세스 토큰. 필수 — 없으면 네트워크 왕복 없이 즉시 실패합니다.	`—`
`VELOCIS_BASE_URL`	백엔드 주소.	`http://localhost:3001`
`VELOCIS_TIMEOUT_MS`	요청 타임아웃(밀리초).	`30000`
`VELOCIS_UPLOAD_TIMEOUT_MS`	첨부 업로드 타임아웃(기본값보다 김, 밀리초).	`120000`
`VELOCIS_MIN_BACKEND_VERSION`	이 빌드가 요구하는 최소 백엔드 릴리스.	`—`
`VELOCIS_SKIP_BACKEND_VERSION_CHECK`	버전 호환성 검사를 끕니다.	`false`

먼저 알아둘 동작

각 도구의 스키마에 전부 적혀 있지만, 놀랄 만한 것만 모았습니다.

조회 범위

상태 필터 없이 이슈 목록을 조회하면 완료·취소된 이슈까지 포함됩니다 — 좁히려면 해당 상태를 명시적으로 제외하세요. 단건 조회는 상태와 무관하게 반환됩니다.

필터가 조용히 넓어질 수 있습니다

인식하지 못한 검색 토큰은 적용되지 않고 버려지며, 그만큼 결과가 넓어집니다. 그 토큰은 응답에 함께 돌아오므로, 필터가 걸린 것처럼 보고하지 말고 고쳐서 다시 호출하세요.

비우기는 생략이 아닙니다

수정 시 담당자·마감일·상위 이슈를 비우려면 명시적으로 빈 값을 넘겨야 합니다. 필드를 아예 넘기지 않으면 그대로 유지됩니다.

태그는 생성 시점에 붙이세요

태그 조건을 건 워크플로 트리거는 이슈 생성 시점에 태그가 있어야만 발화합니다 — 생성 후 붙이면 이미 지나간 이벤트를 되돌릴 수 없습니다.

할당 분배를 직접 계산하지 마세요

추천 도구가 돌려준 날짜별 분배값을 그대로 넘기세요. 평균값 하나로 뭉개면 날짜별 실제 분배가 사라지며, 용량을 초과하면 서버가 거부합니다.

되돌릴 수 없는 것

페이지·첨부 삭제와 모든 대량 삭제는 되돌릴 수 없으며, 명시적인 확인 플래그가 필요합니다.

에러

호출이 실패하면 에러 코드·원인·다음에 할 것을 텍스트로 돌려줍니다 — MCP 응답은 텍스트라 구조화된 객체를 그대로 실을 수 없습니다.

HTTP 상태	코드	뜻
400	`VALIDATION_ERROR`	요청 본문이 거부됨 — 메시지가 문제 필드를 지목합니다.
401	`UNAUTHORIZED`	토큰이 없거나 만료·폐기됨.
403	`PERMISSION_DENIED`	역할이 부족함.
404	`NOT_FOUND`	없거나, 볼 권한이 없어서 없어 보입니다.
409	`CONFLICT`	읽은 뒤 상태가 바뀜 — 다시 읽고 재시도하세요.
429	`RATE_LIMIT_EXCEEDED`	요청이 너무 많음.
5xx	`INTERNAL_ERROR`	요청을 바꿔도 해결되지 않습니다.

사용 가능한 도구

velocis_add_comment

Add a comment to an issue.

velocis_add_issues_to_sprint

Add one or more issues to a sprint.

velocis_add_tag

Attach a tag to an issue.

velocis_advanced_search

Search issues with a multi-condition, JQL-style query string.

velocis_allocate

Book a user's time on an issue across a date range.

velocis_attach_file

Upload local files as attachments on an issue.

velocis_bulk_action

Apply one action to many issues at once.

velocis_complete_sprint

Close a sprint and decide what happens to its unfinished issues.

velocis_create_issue

Create an issue in a project.

velocis_create_milestone

Create a milestone in a project: a wave of an epic or a checkpoint of an initiative.

velocis_create_page

Create a documentation page, with an optional Markdown body.

velocis_create_sprint

Create a sprint in a project.

velocis_delete_attachment

Delete one attachment from an issue.

velocis_delete_milestone

Delete a project's milestone (wave or checkpoint).

velocis_delete_page

Delete a documentation page.

velocis_export_issue_doc

Write an issue's Doc tab to a local Markdown file and return its path.

velocis_find_best_assignee

Rank a project's members for an issue by how well each fits the work, accounting for their remaining capacity.

velocis_find_similar_issues

Find existing issues that look like a draft title — check before filing or starting work.

velocis_get_comments

Read an issue's comment thread, oldest first.

velocis_get_custom_fields

List a project's custom field definitions.

velocis_get_goal

Get one goal with its progress, key results and linked issues.

velocis_get_goals

List the goals you can see, optionally narrowed to specific projects.

velocis_get_issue

Get a single issue by its number or id.

velocis_get_issue_allocations

List who is booked on an issue, and for how many hours per day.

velocis_get_issue_doc

Read an issue's Doc tab as Markdown.

velocis_get_issue_history

Read an issue's full change history: field edits, status transitions, assignee changes and comments.

velocis_get_issue_transitions

Get an issue's current status and the statuses it may move to next.

velocis_get_issues

List issues, with optional filters.

velocis_get_page

Get a documentation page by its slug or id.

velocis_get_project_calendar

Get a project's per-user allocation calendar over a date range.

velocis_get_projects

List the projects you are a member of.

velocis_get_sprint

Get one sprint and its issues, by id, by name, or as the project's current sprint.

velocis_get_sprints

List a project's sprints.

velocis_get_user_work_summary

Summarise one user's work over a date range, grouped by issue.

velocis_get_user_workload

Get a user's allocated, actual and capacity hours per day over a date range.

velocis_get_workflow_meta

Get the workflow rule builder's schema: condition fields, operators and action types.

velocis_get_workspace_calendar

Get the allocation calendar across every project and user.

velocis_link_issues

Link two issues, for example as blocking or related.

velocis_list_milestones

List a project's milestones (waves) with their progress.

velocis_move_allocation

Move an allocation to a different user or date.

velocis_recommend_allocation

Suggest how to spread a total number of hours across days for one user, respecting capacity, weekends and holidays.

velocis_record_qa_result

Record a QA verdict, with an optional structured report, on a test issue.

velocis_remove_allocation

Delete one or more allocations.

velocis_remove_issue_from_sprint

Remove an issue from a sprint.

velocis_remove_tag

Detach a tag from an issue.

velocis_reorder_sibling

Move an issue before or after a sibling in its parent's order.

velocis_replan_allocation

Replace an issue's allocations with a new distribution, in one transaction.

velocis_search_pages

Search documentation pages by keyword, across both titles and page bodies.

velocis_set_issue_favorite

Add an issue to, or remove it from, the caller's own favorites.

velocis_sheets_list_links

List a project's Google Sheets links.

velocis_simulate_allocation

Check whether a set of per-day hours fits a user's remaining capacity, without writing anything.

velocis_unlink_issues

Remove a link between two issues.

velocis_update_issue

Update an issue's fields, such as its assignee, priority, title or due date.

velocis_update_issue_doc

Write an issue's Doc tab from Markdown.

velocis_update_key_result

Update one key result under a goal, for example to log its current value.

velocis_update_milestone

Update, close, reopen or reorder a project's milestone (wave).

velocis_update_page

Update a documentation page's metadata, its Markdown body, or both.

velocis_update_sprint

Update a sprint's name, goal, dates or state.

velocis_update_status

Change an issue's status.

velocis_whoami

Report which credential the server is using and what it can reach — start here when a call is rejected.