| 1 | --- |
| 2 | title: MCP tools |
| 3 | description: Every tool the g1t MCP server exposes, with its required inputs and the matching REST route. |
| 4 | --- |
| 5 | |
| 6 | The MCP server at `https://mcp.g1t.sh` exposes the tools below. Each is the |
| 7 | same operation as a route of the [REST API](/reference/api/), so the two |
| 8 | always agree. To connect a client, see |
| 9 | [connect an agent](/guides/bring-your-own-agent/). |
| 10 | |
| 11 | ## Conventions |
| 12 | |
| 13 | - `repo` is always `owner/name`, such as `"syntaqx/hello"`. |
| 14 | - `number` names an issue or a pull request. The two share one sequence per |
| 15 | repository, so a number names exactly one of them. |
| 16 | - Inputs are `snake_case`. Results are JSON, with `camelCase` fields. |
| 17 | - A tool that fails returns its error as the result, with `isError` set, so |
| 18 | the agent can read it and act on it. |
| 19 | - Reading a public repository needs no sign-in through the API. Through MCP, |
| 20 | every call needs to be signed in. |
| 21 | |
| 22 | Required inputs are listed in each table. Optional inputs are described in |
| 23 | the tool's schema, which `tools/list` returns, and in the |
| 24 | [API reference](/reference/api/). |
| 25 | |
| 26 | ## Account and workspaces |
| 27 | |
| 28 | | Tool | Required | What it does | Route | |
| 29 | | --- | --- | --- | --- | |
| 30 | | `whoami` | | Who the access token acts as, and the workspaces it can work in. `kind` is `user`, `workspace` or `agent`. | [`GET /user`](/reference/api/accounts/whoami/) | |
| 31 | | `create_workspace` | `slug` | Create a workspace. | [`POST /workspaces`](/reference/api/workspaces/create-workspace/) | |
| 32 | |
| 33 | ## Repositories |
| 34 | |
| 35 | | Tool | Required | What it does | Route | |
| 36 | | --- | --- | --- | --- | |
| 37 | | `list_repos` | | Repositories you can see, optionally filtered by `query`. | [`GET /repos?q=`](/reference/api/repositories/list-repos/) | |
| 38 | | `get_repo` | `repo` | One repository's details. | [`GET /repos/{owner}/{name}`](/reference/api/repositories/get-repo/) | |
| 39 | | `create_repo` | `name` | Create a repository in one of your workspaces, empty or as a copy of a public git repository (`import_url`). `workspace` may be left out if you belong to exactly one. | [`POST /repos`](/reference/api/repositories/create-repo/) | |
| 40 | | `update_repo` | `repo` | Change its description, whether it is private, and whether its default branch is protected. Members only. | [`PATCH /repos/{owner}/{name}`](/reference/api/repositories/update-repo/) | |
| 41 | | `get_repo_settings` | `repo` | How it handles pull requests: approvals, checks, being up to date, and how g1t's agents are reviewed, revised and merged. | [`GET /repos/{owner}/{name}/settings`](/reference/api/repositories/get-repo-settings/) | |
| 42 | | `update_repo_settings` | `repo` | Change those settings. Only the fields given change. Members only. | [`PATCH /repos/{owner}/{name}/settings`](/reference/api/repositories/update-repo-settings/) | |
| 43 | | `list_labels` | `repo` | The labels available on its issues. | [`GET /repos/{owner}/{name}/labels`](/reference/api/issues/list-labels/) | |
| 44 | | `list_events` | `repo` | Its timeline, newest first. `before` pages back. | [`GET /repos/{owner}/{name}/events`](/reference/api/repositories/list-events/) | |
| 45 | |
| 46 | `update_repo_settings` takes `required_approvals`, `count_agent_approvals`, |
| 47 | `allow_ignoring_checks`, `require_up_to_date`, `agent_review`, |
| 48 | `max_revisions`, `auto_merge` and `merge_queue`. See |
| 49 | [what a repository can ask for](/guides/g1t-agents/#what-a-repository-can-ask-for). |
| 50 | |
| 51 | ## Issues |
| 52 | |
| 53 | | Tool | Required | What it does | Route | |
| 54 | | --- | --- | --- | --- | |
| 55 | | `list_issues` | `repo` | Issues, newest first, by `state` and `label`. | [`GET /repos/{owner}/{name}/issues`](/reference/api/issues/list-issues/) | |
| 56 | | `get_issue` | `repo`, `number` | An issue: description, labels, acceptance checks, comments, and every pull request made for it. | [`GET /repos/{owner}/{name}/issues/{number}`](/reference/api/issues/get-issue/) | |
| 57 | | `create_issue` | `repo`, `title` | Open an issue, with `body`, `labels` and `checks`. | [`POST /repos/{owner}/{name}/issues`](/reference/api/issues/create-issue/) | |
| 58 | | `update_issue` | `repo`, `number` | Change its title, body, labels or assignees. Labels and assignees each replace the whole set. | [`PATCH /repos/{owner}/{name}/issues/{number}`](/reference/api/issues/update-issue/) | |
| 59 | | `close_issue` | `repo`, `number` | Close it as `completed` or `not_planned`. | [`POST /repos/{owner}/{name}/issues/{number}/close`](/reference/api/issues/close-issue/) | |
| 60 | | `reopen_issue` | `repo`, `number` | Reopen a closed issue. | [`POST /repos/{owner}/{name}/issues/{number}/reopen`](/reference/api/issues/reopen-issue/) | |
| 61 | | `assign_issue` | `repo`, `number` | Assign it to the [g1t agent](/guides/g1t-agents/), which opens a pull request and sees it through. Preview. | [`POST /repos/{owner}/{name}/issues/{number}/assign`](/reference/api/issues/assign-issue/) | |
| 62 | | `add_comment` | `repo`, `number`, `body` | Comment on an issue or a pull request; with `path` and `line`, on one line of a pull request's change. | [`POST /repos/{owner}/{name}/issues/{number}/comments`](/reference/api/issues/add-comment/) | |
| 63 | |
| 64 | ## Pull requests |
| 65 | |
| 66 | | Tool | Required | What it does | Route | |
| 67 | | --- | --- | --- | --- | |
| 68 | | `list_pull_requests` | `repo` | Pull requests, newest first. `open` covers drafts and those ready for review. | [`GET /repos/{owner}/{name}/pulls`](/reference/api/pull-requests/list-pull-requests/) | |
| 69 | | `get_pull_request` | `repo`, `number` | Status, head commit, comments and reviews, its issue, the latest acceptance check results, `behind`, and `overlaps`. | [`GET /repos/{owner}/{name}/pulls/{number}`](/reference/api/pull-requests/get-pull-request/) | |
| 70 | | `create_pull_request` | `repo` | Open a draft pull request with its own fork and get its git remote; or, with `branch`, one from a branch already pushed. Give `issue` whenever there is one. | [`POST /repos/{owner}/{name}/pulls`](/reference/api/pull-requests/create-pull-request/) | |
| 71 | | `get_pull_request_changes` | `repo`, `number` | The files it changes, with line-by-line diffs. | [`GET /repos/{owner}/{name}/pulls/{number}/changes`](/reference/api/pull-requests/get-pull-request-changes/) | |
| 72 | | `mark_pull_request_ready` | `repo`, `number`, `summary` | Mark a draft ready for review. The summary becomes its description. | [`POST /repos/{owner}/{name}/pulls/{number}/ready`](/reference/api/pull-requests/mark-pull-request-ready/) | |
| 73 | | `review_pull_request` | `repo`, `number`, `verdict` | `approve`, or `request_changes` with a `body`. Not on your own pull request. | [`POST /repos/{owner}/{name}/pulls/{number}/reviews`](/reference/api/pull-requests/review-pull-request/) | |
| 74 | | `close_pull_request` | `repo`, `number` | Close it without merging. | [`POST /repos/{owner}/{name}/pulls/{number}/close`](/reference/api/pull-requests/close-pull-request/) | |
| 75 | | `merge_pull_request` | `repo`, `number` | Land it on `main` and resolve its issue, or add it to the [merge queue](/guides/merge-queue/). Members only. | [`POST /repos/{owner}/{name}/pulls/{number}/merge`](/reference/api/pull-requests/merge-pull-request/) | |
| 76 | |
| 77 | ## Sessions |
| 78 | |
| 79 | | Tool | Required | What it does | Route | |
| 80 | | --- | --- | --- | --- | |
| 81 | | `record_session` | `repo`, `number`, `entries` | Append entries to a pull request's session. Each has `kind` and `text`, and `tool` for tool entries. | [`POST /repos/{owner}/{name}/pulls/{number}/session`](/reference/api/sessions/record-session/) | |
| 82 | | `read_session` | `repo`, `number` | The recorded session, oldest first. `after` skips to entries after a sequence number. | [`GET /repos/{owner}/{name}/pulls/{number}/session`](/reference/api/sessions/read-session/) | |
| 83 | |
| 84 | See [sessions and why-blame](/guides/why-blame/). |
| 85 | |
| 86 | ## Plans |
| 87 | |
| 88 | | Tool | Required | What it does | Route | |
| 89 | | --- | --- | --- | --- | |
| 90 | | `plan_work` | `repo`, `brief` | Have an agent turn an outcome into proposed issues with checks and dependencies. Returns the plan's id at once. Members only. | [`POST /repos/{owner}/{name}/plans`](/reference/api/plans/plan-work/) | |
| 91 | | `get_plan` | `repo`, `plan` | The plan: its status (`planning`, `ready`, `failed` or `applied`), the issues it proposes, and once applied, where each stands. | [`GET /repos/{owner}/{name}/plans/{plan}`](/reference/api/plans/get-plan/) | |
| 92 | | `apply_plan` | `repo`, `plan` | Open its issues. `assign` puts g1t agents on them in dependency order; `keep` opens only some, by position from 1. | [`POST /repos/{owner}/{name}/plans/{plan}/apply`](/reference/api/plans/apply-plan/) | |
| 93 | |
| 94 | See [hand off an outcome](/guides/outcomes/). |
| 95 | |
| 96 | ## Merge queue |
| 97 | |
| 98 | | Tool | Required | What it does | Route | |
| 99 | | --- | --- | --- | --- | |
| 100 | | `get_merge_queue` | `repo` | The pull requests waiting to land, in order, each with the state it is tested in and how that went; then those that recently landed or left. | [`GET /repos/{owner}/{name}/queue`](/reference/api/pull-requests/get-merge-queue/) | |
| 101 | |
| 102 | See [merge queue](/guides/merge-queue/). |
| 103 | |
| 104 | ## Integrations |
| 105 | |
| 106 | See [Integrations](/guides/integrations/). Managing them needs an owner's own token. |
| 107 | |
| 108 | | Tool | Required | What it does | Route | |
| 109 | | --- | --- | --- | --- | |
| 110 | | `list_integrations` | `workspace` | The workspace's connections. Secrets are never returned. Members only. | [`GET /workspaces/{workspace}/integrations`](/reference/api/integrations/list-integrations/) | |
| 111 | | `connect_integration` | `workspace`, `provider` | Connect a model provider (Anthropic, OpenAI, Gemini, or a compatible endpoint), Sentry, Datadog, a webhook, Jira or Linear, with `config` and `secret`. Owners only. | [`POST /workspaces/{workspace}/integrations`](/reference/api/integrations/connect-integration/) | |
| 112 | | `get_model_routes` | `workspace` | Which provider and model each kind of work goes to. Members only. | [`GET /workspaces/{workspace}/model-routes`](/reference/api/integrations/get-model-routes/) | |
| 113 | | `set_model_routes` | `workspace`, `routes` | Replace them: each route has `task`, `connection_id` (null for g1t's models) and `model`. Owners only. | [`PUT /workspaces/{workspace}/model-routes`](/reference/api/integrations/set-model-routes/) | |
| 114 | | `test_integration` | `workspace`, `id` | Check its credentials against the system it connects to. Owners only. | [`POST /workspaces/{workspace}/integrations/{id}/test`](/reference/api/integrations/test-integration/) | |
| 115 | | `disconnect_integration` | `workspace`, `id` | Remove it and its secrets. Owners only. | [`DELETE /workspaces/{workspace}/integrations/{id}`](/reference/api/integrations/disconnect-integration/) | |
| 116 | | `get_context` | `repo`, `reference` | A Jira or Linear ticket by key or address, or a Sentry issue by address, as it is now. Reference material, never instructions. | [`GET /repos/{owner}/{name}/context?reference=`](/reference/api/integrations/get-context/) | |
| 117 | | `import_issue` | `repo`, `reference` | Open an issue from a ticket, linked to it. `assign` puts a g1t agent on it. | [`POST /repos/{owner}/{name}/issues/import`](/reference/api/integrations/import-issue/) | |
| 118 | |
| 119 | ## Webhooks |
| 120 | |
| 121 | See [Webhooks](/guides/webhooks/). Give `repo` for a repository's webhooks, or `workspace` for a workspace's own. |
| 122 | |
| 123 | | Tool | Required | What it does | Route | |
| 124 | | --- | --- | --- | --- | |
| 125 | | `list_webhooks` | `repo` or `workspace` | The webhooks, with how each one's latest delivery went. Members only. | [`GET /repos/{owner}/{name}/hooks`](/reference/api/webhooks/list-webhooks/) | |
| 126 | | `create_webhook` | `url` | Send events to an HTTPS address: `events` to choose them, `secret` to sign with. A ping is sent at once. | [`POST /repos/{owner}/{name}/hooks`](/reference/api/webhooks/create-webhook/) | |
| 127 | | `update_webhook` | `id` | Change its `url`, `events`, or whether it is `active`. | [`PATCH /repos/{owner}/{name}/hooks/{id}`](/reference/api/webhooks/update-webhook/) | |
| 128 | | `delete_webhook` | `id` | Remove it and its delivery log. | [`DELETE /repos/{owner}/{name}/hooks/{id}`](/reference/api/webhooks/delete-webhook/) | |
| 129 | | `ping_webhook` | `id` | Send it a ping. | [`POST /repos/{owner}/{name}/hooks/{id}/pings`](/reference/api/webhooks/ping-webhook/) | |
| 130 | | `list_webhook_deliveries` | `id` | Its latest deliveries, with request, response and retries. | [`GET /repos/{owner}/{name}/hooks/{id}/deliveries`](/reference/api/webhooks/list-webhook-deliveries/) | |
| 131 | | `redeliver_webhook` | `id`, `delivery` | Send a delivery again. | [`POST /repos/{owner}/{name}/hooks/{id}/deliveries/{delivery}/redeliver`](/reference/api/webhooks/redeliver-webhook/) | |
| 132 | |
| 133 | Each has a workspace route too, under `/workspaces/{workspace}/hooks`. |
| 134 | |
| 135 | ## GitHub Actions |
| 136 | |
| 137 | See [GitHub Actions](/guides/actions/). Workflows are GitHub's, kept in `.g1t/workflows/`. Routes are GitHub's own. |
| 138 | |
| 139 | | Tool | Required | What it does | Route | |
| 140 | | --- | --- | --- | --- | |
| 141 | | `list_workflows` | `repo` | The workflows, with their events, state, problems, notes on what runs differently, manual-run inputs and last run. | [`GET /repos/{owner}/{name}/actions/workflows`](/reference/api/actions/list-workflows/) | |
| 142 | | `list_workflow_runs` | `repo` | Runs, newest first; filter by `workflow`, `branch`, `event`, `pull` or `sha`. | [`GET /repos/{owner}/{name}/actions/runs`](/reference/api/actions/list-runs-of-workflow/) | |
| 143 | | `get_workflow_run` | `repo`, `id` | A run with its jobs, their steps and annotations. | [`GET /repos/{owner}/{name}/actions/runs/{id}`](/reference/api/actions/get-workflow-run/) | |
| 144 | | `get_job_logs` | `repo`, `job` | A job's log after `after`; `done` says if more will come. | [`GET /repos/{owner}/{name}/actions/jobs/{job}/logs`](/reference/api/actions/get-job-logs/) | |
| 145 | | `dispatch_workflow` | `repo`, `workflow` | Run a `workflow_dispatch` workflow on `ref` with `inputs`. Members only. | [`POST /repos/{owner}/{name}/actions/workflows/{workflow}/dispatches`](/reference/api/actions/dispatch-workflow/) | |
| 146 | | `cancel_workflow_run` | `repo`, `id` | Cancel a run. Members only. | [`POST /repos/{owner}/{name}/actions/runs/{id}/cancel`](/reference/api/actions/cancel-workflow-run/) | |
| 147 | | `rerun_workflow_run` | `repo`, `id` | Run it again; `failed_only` for the jobs that did not succeed. Members only. | [`POST /repos/{owner}/{name}/actions/runs/{id}/rerun`](/reference/api/actions/rerun-workflow-run/) | |
| 148 | | `update_workflow` | `repo`, `workflow`, `enabled` | Turn a workflow on or off. Members only. | [`PATCH /repos/{owner}/{name}/actions/workflows/{workflow}`](/reference/api/actions/update-workflow/) | |
| 149 | | `list_actions_secrets` | `repo` or `workspace` | Secrets' rows: key, environments, who reads them. Never values. | [`GET /repos/{owner}/{name}/actions/secrets`, `GET /workspaces/{workspace}/actions/secrets`](/reference/api/secrets-and-variables/list-actions-secrets/) | |
| 150 | | `set_actions_secret` | `setting` | Add or change a secret's row: `value`, and optionally `id`, `environments`, `available_to`, `repositories`, `note`. | [`PUT …/actions/secrets/{name}`](/reference/api/secrets-and-variables/set-actions-secret/) | |
| 151 | | `delete_actions_secret` | `setting` | Remove one row (`id`) or every row of the key. | [`DELETE …/actions/secrets/{name}`](/reference/api/secrets-and-variables/delete-actions-secret/) | |
| 152 | | `list_actions_variables` | `repo` or `workspace` | Config rows with their values. | [`GET …/actions/variables`](/reference/api/secrets-and-variables/list-actions-variables/) | |
| 153 | | `set_actions_variable` | `setting` | Add or change a config row, as for secrets. | [`POST …/actions/variables`, `PATCH …/variables/{name}`](/reference/api/secrets-and-variables/set-actions-variable/) | |
| 154 | | `delete_actions_variable` | `setting` | Remove one row (`id`) or every row of the key. | [`DELETE …/actions/variables/{name}`](/reference/api/secrets-and-variables/delete-actions-variable/) | |
| 155 | |
| 156 | ## Messages |
| 157 | |
| 158 | | Tool | Required | What it does | Route | |
| 159 | | --- | --- | --- | --- | |
| 160 | | `message_agent` | `repo`, `number`, `body` | Send the agent working on a pull request a message, received at its next step. A g1t agent sends a `question` or a `handoff`, with its own pull request as `from_number`. | [`POST /repos/{owner}/{name}/pulls/{number}/messages`](/reference/api/pull-requests/message-agent/) | |
| 161 | | `answer_message` | `repo`, `id`, `body` | Answer a question or a handoff by the message's id; `decline` a handoff that is not yours. The answer reaches the asking agent at its next step. | [`POST /repos/{owner}/{name}/messages/{id}/answer`](/reference/api/pull-requests/answer-message/) | |
| 162 | | `take_messages` | `repo`, `number` | For a g1t agent at work: the messages it has not seen yet, each returned once. | [`POST /repos/{owner}/{name}/pulls/{number}/messages/take`](/reference/api/pull-requests/take-messages/) | |
| 163 | |
| 164 | See [talk to agents](/guides/talking-to-agents/). |
| 165 | |
| 166 | ## What a g1t agent can use |
| 167 | |
| 168 | A g1t agent works with a token limited to its own repository and to these |
| 169 | tools: `get_repo`, `list_issues`, `get_issue`, `list_labels`, |
| 170 | `create_issue`, `add_comment`, `list_pull_requests`, `get_pull_request`, |
| 171 | `get_pull_request_changes`, `read_session`, `get_merge_queue`, |
| 172 | `list_events`, `take_messages`, `message_agent`, `answer_message` and `get_context`. |
| 173 | `tools/list` shows such a token only the tools it may use. |