aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

agent_auth

Start, check, respond to, or cancel official CLI authentication for supported coding harnesses, displaying auth URLs, codes, and choices while leaving credential storage to each CLI.

Instructions

各harnessの公式CLI認証を開始・確認・取消する。CLIごとのコマンドと認証URL/codeの抽出はAitermが所有し、資格情報は各CLIだけが保存する。auth_uiの段階と公式URL・選択肢を表示する。入力はrespondで同じbindingへ送り、pty_send／pty_keyへ認証コードを渡さない。authenticatedは認証の結果であり、agent_launchの起動準備完了とは別。remoteは他toolと同じ標準対応。startは公式の状態が認証済みなら何も起こさずauthenticatedを返す。relogin:trueを付けると、認証済みに見えても公式ログインを開始する（別のアカウントへ入り直す時、ログインの期限切れを状態から見抜けない時）。Aitermは資格情報を消さず、置き換えは公式CLIが行う。Codexの公式ログインは、始めた時点で元のログインを消す（途中でcancelしても戻らない）。Antigravityのreloginは未対応を返す。

Input Schema

Name	Required	Description
`cwd`	No	公式CLIを実行する作業ディレクトリの絶対パス
`action`	Yes
`remote`	No	別端末のAitermで実行する時のSSH接続情報。hostだけならssh_configの接続名として使う。Aitermは接続情報を保存・管理しない。passphraseは会話記録に残るため、ssh-agentかpassphrase_env（環境変数名）を推奨する。
`harness`	Yes
`relogin`	No	startで、公式の状態が認証済みでも公式ログインを開始する。既定false。trueの時、authenticatedかつsession_idがnullの結果は返さない
`env_vars`	No	startで認証PTYへ引き継ぐ環境変数名。値はreceiptへ返さない
`response`	No
`session_id`	No
`expected_binding`	No
`expected_prompt_digest`	No

Output Schema

Name	Required	Description	Default
`url`	Yes
`schema`	Yes
`status`	Yes
`auth_ui`	No
`harness`	Yes
`message`	Yes
`user_code`	Yes
`session_id`	Yes
`input_required`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.62.2Oct 30, 2026

changedInput schema / properties / harness / enum

Previous value: -[
-  "claude-code",
-  "codex-cli",
-  "grok-cli",
-  "cursor-cli"
-]New value: +[
+  "claude-code",
+  "codex-cli",
+  "grok-cli",
+  "cursor-cli",
+  "antigravity-cli"
+]

changedOutput schema / properties / harness / enum

Previous value: -[
-  "claude-code",
-  "codex-cli",
-  "grok-cli",
-  "cursor-cli"
-]New value: +[
+  "claude-code",
+  "codex-cli",
+  "grok-cli",
+  "cursor-cli",
+  "antigravity-cli"
+]

Changed5 schema fields changedv0.61.24Oct 28, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "start",
-  "status",
-  "cancel"
-]New value: +[
+  "start",
+  "status",
+  "cancel",
+  "respond"
+]

addedInput schema / properties / expected_binding

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "launch_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "metadata_identity": {
+      "type": "string"
+    },
+    "native_id": {
+      "type": "string"
+    },
+    "pane_id": {
+      "type": "string"
+    },
+    "pane_pid": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "pane_started": {
+      "type": "string"
+    },
+    "server_pid": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "server_started": {
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "session_id",
+    "launch_id",
+    "metadata_identity",
+    "native_id",
+    "pane_id",
+    "server_pid",
+    "server_started",
+    "pane_pid",
+    "pane_started"
+  ],
+  "type": "object"
+}

addedInput schema / properties / expected_prompt_digest

Added value: +{
+  "pattern": "^[a-f0-9]{64}$",
+  "type": "string"
+}

addedInput schema / properties / response

Added value: +{
+  "oneOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "const": "authorization_code",
+          "type": "string"
+        },
+        "value": {
+          "maxLength": 8192,
+          "minLength": 1,
+          "pattern": "^[!-~]+$",
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "value"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "pattern": "^option-[1-9]$",
+          "type": "string"
+        },
+        "kind": {
+          "const": "choice",
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "id"
+      ],
+      "type": "object"
+    }
+  ]
+}

addedOutput schema / properties / auth_ui

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "binding": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "launch_id": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "metadata_identity": {
+              "type": "string"
+            },
+            "native_id": {
+              "type": "string"
+            },
+            "pane_id": {
+              "type": "string"
+            },
+            "pane_pid": {
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            },
+            "pane_started": {
+              "type": "string"
+            },
+            "server_pid": {
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            },
+            "server_started": {
+              "type": "string"
+            },
+            "session_id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "session_id",
+            "launch_id",
+            "metadata_identity",
+            "native_id",
+            "pane_id",
+            "server_pid",
+            "server_started",
+            "pane_pid",
+            "pane_started"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "choices": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "label"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "input": {
+      "anyOf": [
+        {
+          "enum": [
+            "authorization_code",
+            "choice"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "message": {
+      "type": "string"
+    },
+    "prompt_digest": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "schema": {
+      "const": "aiterm.auth-ui.v1",
+      "type": "string"
+    },
+    "stage": {
+      "enum": [
+        "open_url",
+        "device_code",
+        "paste_code",
+        "select",
+        "waiting",
+        "complete",
+        "failed",
+        "unavailable"
+      ],
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "user_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "schema",
+    "stage",
+    "title",
+    "message",
+    "binding",
+    "url",
+    "user_code",
+    "input",
+    "prompt_digest",
+    "choices"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.60.1Oct 14, 2026

addedInput schema / properties / relogin

Added value: +{
+  "description": "startで、公式の状態が認証済みでも公式ログインを開始する。既定false。trueの時、authenticatedかつsession_idがnullの結果は返さない",
+  "type": "boolean"
+}

Addedv0.46.1Oct 2, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden well: it warns that Codex deletes the original login at start (even on cancel), that Antigravity relogin is unsupported, and that Aiterm itself never deletes credentials. It stops short of describing response/pagination or rate/session behavior, but the destructive-action disclosures are strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then progressively narrower operational notes. Every clause is relevant, though the density and run-on structure means it is less skimmable than it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Has an output schema (so return values needn't be explained) and the description covers mutation hazards, no-op behavior, and unsupported cases. The main remaining gap is the unmentioned binding/session digest parameters, which matters for a 10-param nested tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 40%, so the description must compensate. It clarifies relogin semantics and respond targeting, but says nothing about session_id, expected_binding, expected_prompt_digest, or env_vars beyond what the schema states. Marginal value beyond structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb set (start/check/cancel) and resource (official CLI authentication per harness), which an agent can tell apart from siblings like pty_send and agent_launch. It also clarifies the division of labor: Aiterm extracts commands/URLs, but each CLI stores credentials.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit alternatives and exclusions: respond to the same binding, never pass auth codes to pty_send/pty_key, use relogin:true when the account must be switched or expiry can't be seen, and authenticated ≠ agent_launch readiness. These are concrete when/when-not rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.