Gentic MCP Tools Reference: Projects, Issues, Relations, and Labels

Gentic’s MCP server exposes tools your AI assistant can call once you have connected and authorized via OAuth 2.0. This reference groups them into five categories — Account, Projects, Issues, Issue Relations, and Labels — covering project management, the full issue lifecycle, blocking dependencies between issues, and account-scoped Label organization. For the concepts behind blocking relations, see the Issue Relations guide. Uploading attachments, sending messages, retrying runs, and GitHub integration settings remain web-app workflows. All tools require an active, authorized MCP session; unauthenticated calls are rejected automatically.

Account

`whoami`

Returns the Gentic account ID associated with the current MCP connection. Use this to confirm which account your client has authorized and to retrieve the user ID for reference.

Show Output fields

string

The unique Gentic account ID for the authorized session.

Projects

`list_projects`

Lists all Gentic projects owned by the authenticated account. Use the returned project IDs as project_id when creating or filtering issues.

Show Output fields

array

An array of project objects owned by the authenticated account.

`get_project`

Returns full details for a single project. Use the project ID from list_projects.

string (uuid)

required

The project ID, from list_projects or get_project.

Show Output fields

object

The matching project object.

`create_project`

Creates a new Gentic project linked to a GitHub repository.

string

required

Human-readable project name shown in Gentic. Maximum 120 characters.

string

required

GitHub repository in owner/name format, for example vercel/next.js.

string

Optional shell script run by the background agent after cloning the repository. Maximum 10,000 characters. Pass null to leave it unset.

Show Output fields

object

The newly created project object.

`update_project`

Updates the name, repository, or setup script for an existing project. You must supply all three editable fields — any field you do not want to change should be passed with its current value.

string (uuid)

required

The project ID, from list_projects or get_project.

string

required

Updated human-readable project name. Maximum 120 characters.

string

required

Updated GitHub repository in owner/name format.

string | null

required

Updated shell setup script. Pass null to remove the existing script.

Show Output fields

object

The updated project object.

`delete_project`

Permanently deletes a project and all of its issues. All issues belonging to the project are removed at the same time.

Deleting a project is irreversible. All issues within the project are also deleted immediately.

string (uuid)

required

The project ID to delete.

Show Output fields

string (uuid)

The ID of the deleted project.

boolean

Always true when the deletion completed successfully.

Issues

`list_issues`

Lists issues owned by the authenticated account. Filter by project and/or by Label to narrow results. Returned issue objects include priority and their assigned active labels.

string (uuid)

Optional. When provided, returns only issues belonging to this project. Omit to list issues across all projects.

array of string (uuid)

Optional stable Label IDs. Returns only issues that carry every supplied Label (match-all). Up to 20 IDs; duplicates are ignored. Cannot be combined with unlabeled. Archived, missing, or foreign Label IDs are rejected rather than treated as an empty match.

boolean

default:"false"

Optional. When true, returns only issues that have no active Labels — useful for finding work that still needs classification. Cannot be combined with label_ids.

Show Output fields

array

An array of issue objects matching the filter. Each issue includes a labels array of its assigned active Labels (id, name, color), ordered case-insensitively by name.

`get_issue`

Returns full details for a single issue, including its current status, priority, body, agent configuration, assigned active Labels, and the metadata of its active durable Issue Attachments.

string

required

The issue’s human-readable Issue Code such as GEN-123, built from the project key and issue number returned by list_issues or create_issue.

Show Output fields

object

The matching issue object.

array

The issue’s assigned active Labels, each with id, name, and color, ordered case-insensitively by name. Archived Labels are excluded.

array

Active durable Issue Attachments, oldest first, as metadata only — id, file_name, content_type, and size_bytes. Message Attachments are excluded, and the file bytes are never inlined. Pass an attachment id to download_attachment to fetch the file.

`download_attachment`

Returns a fresh, short-lived signed download URL for one active durable Issue Attachment. The response carries a URL to fetch the bytes, never the bytes themselves. Message Attachments, deleted or incomplete uploads, and attachments on other accounts’ issues are all rejected as not found without leaking storage details.

string (uuid)

required

The Issue Attachment ID, taken from issue.attachments in the get_issue response.

Show Output fields

string (uuid)

The attachment ID that was passed in.

string

The attachment’s original file name.

string | null

The MIME content type, or null when it is unknown.

number | null

The file size in bytes, or null when it is unknown.

string

A fresh, short-lived signed URL. Fetch it directly to download the file.

number

Seconds until the signed URL expires.

`create_issue`

Creates a new issue inside a project. Issues are created in draft status by default, giving you the chance to refine the title and issue body before queuing a run.

string (uuid)

required

The ID of the project to create this issue in. Obtain it from list_projects.

string

required

Short issue title shown in the Gentic dashboard. Maximum 160 characters.

string

Detailed instructions for the background coding agent. Explain the problem, expected behavior, and any relevant context. The agent uses this body as its primary directive when the issue is queued.

enum

Initial workflow status for the issue. Defaults to draft.Accepted values: draft, todo, queued, held, in-progress, waiting-for-input, testing, tests-failed, ready-for-review, changes-requested, approved, merged, deploying, deploy-failed, validating, run-failed, completed, cancelled

enum

Issue priority. Defaults to medium.Accepted values: low, medium, high, urgent

enum

The AI coding agent to assign to this issue. Defaults to claude_code.Accepted values: claude_code, codex

enum

Categorizes the nature of the issue. Defaults to feature.Accepted values: feature, bug, feedback, idea, specA spec issue records intent instead of requesting work: no host ever claims it and it has no agent conversation. See Spec issues.

boolean

Whether Gentic automatically opens a pull request when the agent finishes. Defaults to true. Set to false to have the agent stop before publishing a PR.

array of string (uuid)

Optional stable Label IDs to assign at creation, from list_labels or create_label. Up to 20 per issue. Every ID must be an active Label owned by the authenticated account, or the whole call is rejected and no issue is created — initial assignment is atomic with issue creation.

Show Output fields

object

The newly created issue object.

`update_issue`

Updates the title, body, agent provider, issue model, type, and priority for an existing issue. Use this to refine the agent’s instructions before queuing a run. title, agent_provider, type, and priority are required; body and issue_model are optional.

string (uuid)

required

The issue ID to update.

string

required

Updated short issue title. Maximum 160 characters.

string

Updated detailed instructions for the background coding agent. Optional — omit to leave the body unchanged.

enum

required

Coding agent to assign to this issue.Accepted values: claude_code, codex

string

Optional coding-agent model to run for this issue. Omit or pass null to use the provider default.

enum

required

Updated issue type.Accepted values: feature, bug, feedback, idea, specSwitching an issue to spec is rejected while an agent run is active on it, because a spec has no conversation for the run to report into.

enum

required

Updated issue priority.Accepted values: low, medium, high, urgent

boolean

Whether Gentic automatically opens a pull request when the agent finishes. Omit to leave the current value unchanged. Ignored once the issue already has an attached pull request.

Show Output fields

object

The updated issue object.

`delete_issue`

Permanently deletes an issue. This action cannot be undone.

string (uuid)

required

The issue ID to delete.

Show Output fields

string (uuid)

The ID of the deleted issue.

boolean

Always true when the deletion completed successfully.

`update_issue_priority`

Updates only the priority for an existing issue and records priority_changed history when the value changes.

string (uuid)

required

The issue ID to update.

enum

required

New issue priority.Accepted values: low, medium, high, urgent

Show Output fields

object

The updated issue object, reflecting the new priority.

`update_issue_status`

Moves an issue to a new workflow status. This is the primary tool for driving an issue through the Gentic pipeline after it has been created and refined.

string (uuid)

required

The issue ID to update.

enum

required

New workflow status for the issue.Accepted values: draft, todo, queued, held, in-progress, waiting-for-input, testing, tests-failed, ready-for-review, changes-requested, approved, merged, deploying, deploy-failed, validating, run-failed, completed, cancelledSee Issue Statuses for what each value means and the transitions the host drives automatically.

Moving an issue from draft → todo is the trigger for a background agent run. Gentic drops the issue into the unclaimed pool, creates the kickoff message Work on Gentic issue {Issue Code}. (the agent reads the body itself via get_issue), and the next available host claims it (flipping it to queued, then in-progress once the agent session starts). Other status transitions update the workflow state only — they do not start or restart an agent run.A spec issue is the exception: it is never claimed, so draft → todo on a spec sets the status and nothing else.

Show Output fields

object

The updated issue object, reflecting the new status.

Issue Relations

Relations declare a blocking dependency between two issues you own: one issue must reach completed or cancelled before the other becomes eligible for a host. Enforcement happens when a host polls for work — a blocked issue can sit in todo indefinitely and is simply skipped. See the Issue Relations guide for the workflow behind them. All four tools identify issues by their id (uuid), not their Issue Code. Every relation is of type blocks; the direction argument on add_issue_relation is what decides which end blocks which.

`list_issue_relations`

Lists every blocking relation involving one issue — both the issues it blocks and the issues blocking it — newest first.

string (uuid)

required

The issue ID, from list_issues, create_issue, or get_issue.

Show Output fields

array

Blocking relations involving the issue, newest first. Each relation carries id (the relation ID, needed for delete_issue_relation), source_issue_id, target_issue_id, type (always blocks), and created_at, plus embedded source_issue and target_issue objects with id, number, title, status, and their project key.

The relation always reads source blocks target. To know which side the issue you queried is on, compare its ID against source_issue_id and target_issue_id.

`list_issue_relation_candidates`

Lists the other issues in your account that could be related to a given issue, newest first. Use it to resolve a title into the related_issue_id that add_issue_relation needs.

string (uuid)

required

The issue ID the candidates would be related to. This issue is excluded from the results.

Show Output fields

array

Other issues owned by the authenticated account, newest first, each with id, number, title, status, and their project key. Candidates span every project and every status, and issues already related to this one are not filtered out — check list_issue_relations first to avoid a duplicate.

`add_issue_relation`

Creates a blocking relation between two issues you own.

string (uuid)

required

The issue the relation is being added from, from list_issues, create_issue, or get_issue.

The other issue to relate to issue_id, from list_issues or list_issue_relation_candidates. Must be a different issue — relating an issue to itself is rejected.

enum

required

Which way the dependency runs.Accepted values: blocking, blocked_by

blocking — issue_id blocks related_issue_id, so related_issue_id waits.
blocked_by — issue_id is blocked by related_issue_id, so issue_id waits.

Show Output fields

string (uuid)

The issue ID passed as issue_id.

The issue ID passed as related_issue_id.

boolean

Always true when the relation was created.

Relations are not idempotent. Re-adding a pair that already exists in the same direction is rejected as a duplicate rather than silently succeeding, so a blind retry after a timeout can surface an error even though the first call landed.

`delete_issue_relation`

Removes a blocking relation. The blocked issue becomes eligible for a host on its next poll.

string (uuid)

required

The relation ID, from the relations array returned by list_issue_relations. This is the relation’s own ID, not an issue ID.

string (uuid)

required

An issue ID on either end of the relation, used to look it up. The relation is rejected as not found if it does not touch this issue.

Show Output fields

string (uuid)

The ID of the deleted relation.

boolean

Always true when the deletion completed successfully.

Labels

Labels are reusable, account-scoped classifications you can assign to issues in any project you own. They are passive metadata — assigning a Label never changes status, priority, host selection, agent scheduling, prompts, or sessions — and they are never synchronized to GitHub. See the Labels guide for the full model. Every Label mutation identifies the Label by its stable id, never its display name, so renames never make a reference ambiguous. Colors are opaque #RRGGBB values. The catalog is capped at 100 active Labels per account, an issue holds at most 20 Labels, and a single add/remove call spans at most 100 issues.

`list_labels`

Lists your active account Labels, ordered alphabetically (case-insensitive). Archived Labels are never returned.

string

Optional case-insensitive substring match on Label name. Maximum 50 characters.

Show Output fields

array

Active account Labels, each with id (uuid), name, color (#RRGGBB), and assignment_count — the number of issues carrying the Label across every status.

`create_label`

Creates an active account Label, or restores an archived one. If an archived Label already has the same name (trimmed, case-insensitive), it is restored — reviving its original id, display casing, and color — and restored is true.

string

required

1–50 characters after trimming. Unicode and spaces allowed; control characters rejected. Must be unique per account (case-insensitively) across active and archived Labels. A collision with an active name is rejected.

#RRGGBB

Optional. Omit to have Gentic pick one of the least-used preset colors. When restoring an archived Label, any supplied color (and casing) is ignored in favor of the Label’s original values.

Show Output fields

object

The created or restored Label (id, name, color, assignment_count).

boolean

true when an archived Label of the same name was restored instead of a new Label being created; otherwise false.

Restoration respects the 100-active-Label limit and does not re-attach the Label’s former issue assignments — a restored Label comes back empty.

`update_label`

Renames and/or recolors an active Label by its stable ID. Name collisions with any active or archived Label are rejected without merging identities. Provide at least one of name or color.

string (uuid)

required

The stable Label ID, from list_labels or create_label.

string

Optional new name. Same rules as create_label.

#RRGGBB

Optional new color.

Show Output fields

object

The updated Label (id, name, color, assignment_count).

`archive_label`

Archives an active Label by its stable ID. Archiving atomically removes the Label from every issue that carries it — any number, including none — records one grouped removal entry on each affected issue’s timeline, and drops the Label from listing, assignment, and filtering. This replaces permanent deletion; former assignments are not recoverable, but re-creating the same name later restores the Label’s original identity.

string (uuid)

required

The stable Label ID to archive.

Show Output fields

string (uuid)

The ID of the archived Label.

boolean

Always true when archival completed successfully.

number

The number of issues the Label was removed from, across every issue status. Zero when it had no assignments.

`add_issue_labels`

Assigns one or more active Labels to one or more issues. Idempotent — already-assigned pairs are no-ops, so retries are safe. Validated atomically: if any issue ID or Label ID is missing, not owned by the caller, archived, or would push an issue past 20 Labels, the whole call is rejected and nothing changes.

array of string (uuid)

required

1–100 issue IDs. Duplicates are ignored. Issues may span different projects.

array of string (uuid)

required

1–20 active Label IDs. Duplicates are ignored.

Show Output fields

array

The issue IDs the operation applied to.

array

The Label IDs that were added.

boolean

Always true when the operation completed successfully.

`remove_issue_labels`

Removes one or more Labels from one or more issues. Idempotent — pairs that aren’t assigned are no-ops. Works at every issue status, including when an issue already holds 20 Labels. Validated atomically the same way as add_issue_labels.

array of string (uuid)

required

1–100 issue IDs. Duplicates are ignored. Issues may span different projects.

array of string (uuid)

required

1–20 Label IDs. Duplicates are ignored.

Show Output fields

array

The issue IDs the operation applied to.

array

The Label IDs that were removed.

boolean

Always true when the operation completed successfully.

There is no archive-list or restore tool. list_labels never returns archived Labels, and restoration happens through create_label by name. Assigning or filtering by an archived Label ID is rejected as not-found so stale state is visible rather than silently ignored.

Practical example: create and queue an issue

The most common pattern is to create an issue in draft state, optionally review or update it, then transition it to todo to start the agent run. You can instruct your assistant with a single natural-language request:

“Create a bug issue for project abc-123 titled ‘Fix null pointer in auth’ with body ‘The login endpoint throws NPE when email is missing. Add input validation.’ then move it to todo.”

Your assistant will execute two tool calls in sequence: Step 1 — create_issue

{
  "project_id": "abc-123",
  "title": "Fix null pointer in auth",
  "body": "The login endpoint throws NPE when email is missing. Add input validation.",
  "type": "bug",
  "status": "draft",
  "agent_provider": "claude_code"
}

Step 2 — update_issue_status

{
  "id": "<id returned from create_issue>",
  "status": "todo"
}

The draft → todo transition queues the background agent run. From this point, Gentic takes over: the agent clones the repository, applies the fix described in the body, and advances the issue status as it progresses.

If you want to review or edit the body before the agent starts, tell your assistant to create the issue in draft and stop. Come back later and ask it to move the issue to todo when you are ready.

Get Started

Web App

Agent Host

MCP Integration

Guides

Gentic MCP Tools Reference: Projects, Issues, Relations, and Labels

Account

`whoami`

Projects

`list_projects`

`get_project`

`create_project`

`update_project`

`delete_project`

Issues

`list_issues`

`get_issue`

`download_attachment`

`create_issue`

`update_issue`

`delete_issue`

`update_issue_priority`

`update_issue_status`

Issue Relations

`list_issue_relations`

`list_issue_relation_candidates`

`add_issue_relation`

`delete_issue_relation`

Labels

`list_labels`

`create_label`

`update_label`

`archive_label`

`add_issue_labels`

`remove_issue_labels`

Practical example: create and queue an issue

​Account

​whoami

​Projects

​list_projects

​get_project

​create_project

​update_project

​delete_project

​Issues

​list_issues

​get_issue

​download_attachment

​create_issue

​update_issue

​delete_issue

​update_issue_priority

​update_issue_status

​Issue Relations

​list_issue_relations

​list_issue_relation_candidates

​add_issue_relation

​delete_issue_relation

​Labels

​list_labels

​create_label

​update_label

​archive_label

​add_issue_labels

​remove_issue_labels

​Practical example: create and queue an issue

Account

`whoami`

Projects

`list_projects`

`get_project`

`create_project`

`update_project`

`delete_project`

Issues

`list_issues`

`get_issue`

`download_attachment`

`create_issue`

`update_issue`

`delete_issue`

`update_issue_priority`

`update_issue_status`

Issue Relations

`list_issue_relations`

`list_issue_relation_candidates`

`add_issue_relation`

`delete_issue_relation`

Labels

`list_labels`

`create_label`

`update_label`

`archive_label`

`add_issue_labels`

`remove_issue_labels`

Practical example: create and queue an issue