Skip to main content
Glama

Connect GitHub

github_connect

Connect or replace a GitHub credential without pasting a token: start a device flow, show the code, then poll for authorization; tokens go to the encrypted vault and are never returned.

Instructions

Connect GitHub with Device Flow. action=start returns verification_uri and user_code: show them to the user, then action=poll with pending_id after they authorize. Tokens go to the encrypted vault and are never returned. Use when: the user wants to connect or replace the GitHub credential without pasting a token. Avoid when: you only need public read access, or a token is already configured. Output: start: verification_uri, user_code, pending_id, expiry. poll: pending | denied | expired | connected.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "github_connect"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYesstart: begin the device flow (returns verification_uri + user_code). poll: check with pending_id whether the user authorized.
pending_idNoaction=poll: opaque id returned by action=start; it does not contain the device code or token.
replace_existingNoaction=start: 1 explicitly authorizes replacing an existing GitHub credential; 0 does not.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv4.5.0
    • removedInput schema / properties / replace_existing / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • removedInput schema / properties / replace_existing / maximum
      Removed value: -1
    • removedInput schema / properties / replace_existing / minimum
      Removed value: -0
    • changedInput schema / properties / replace_existing / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.5/5.0
Behavior4/5

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

Adds substantial context beyond the annotations: tokens are written to an encrypted vault and are never returned to the caller, and the poll step yields one of four terminal/transient states (pending | denied | expired | connected). It also signals that an existing credential can be replaced, which is a side effect the annotations only hint at via destructiveHint=false. It stops short of saying whether replacing invalidates the old credential immediately or what to do on expiry, so it is strong but not exhaustive.

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

Conciseness5/5

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

Front-loaded with the mechanism, then the two-step call sequence, then when/when-not, then the return shape. No filler sentences; every clause carries operational information.

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

Completeness5/5

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

No output schema exists, and the description compensates by enumerating the fields returned by start and the status values returned by poll. Combined with the annotations covering open-world and non-idempotent behavior, an agent has everything needed to execute both phases without guessing.

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 100% and the enum for action, the opaque nature of pending_id, and replace_existing are all already documented in the schema. The description's added value is the calling order between the two actions and the fact that pending_id comes from start; it does not explain replace_existing semantics beyond what the schema already says. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Connect GitHub with Device Flow') and immediately pins down what the tool actually is: an OAuth device-flow handshake, not a git operation on repos. The 'Use when' / 'Avoid when' framing separates it from the git_* siblings and from whatever tool supplies a pre-existing token.

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?

Gives an explicit positive trigger ('user wants to connect or replace the GitHub credential without pasting a token') and an explicit exclusion ('only need public read access, or a token is already configured'), plus the in-tool sequencing rule: call start, show the code to the user, then poll with pending_id after they authorize.

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