Skip to main content
Glama

Add an SSH public key

add_ssh_key

Registers an OpenSSH public key to the API key's person so they can connect to SSH-enabled computers, with optional challenge-signature proof.

Instructions

Register an OpenSSH public key to the person this API key belongs to. It is accepted only by computers with SSH on in the account this credential acts on, and is removed when the credential is revoked. Accepted: Ed25519, ECDSA (P-256, P-384, P-521), their security-key forms, and RSA of at least 3072 bits. Refused: DSA, shorter RSA, certificates, a line with SSH options in front of the key, and anything but one key on one line. A key can belong to one person only, and each person may hold eight. Never send a PRIVATE key. PROOF: without challenge and signature the key is UNPROVEN and connects to a computer named by its id only (a computer named by its name is refused). To make it proven, call ssh_key_challenge, have the person run its sign_command with their private key file, and send the challenge and the signature it prints here; a key already registered without proof, to anyone, is then replaced and registered to this person.

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": {
      "public_key": "<public_key>"
    },
    "name": "add_ssh_key"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoA label, up to 60 characters. Defaults to the comment on the line.
challengeNoA challenge from ssh_key_challenge, exactly as issued (sshkc-…). Send it with signature, or leave both out. A challenge is not a credential: it is single-use and only for this person.
signatureNoThe armored signature the challenge's sign_command printed, from -----BEGIN SSH SIGNATURE----- to -----END SSH SIGNATURE-----, made with this key. Send it with challenge, or leave both out.
public_keyYesOne line from a .pub file: "<type> <base64> [comment]". The file's contents can be passed as read: surrounding whitespace, including a trailing newline, is dropped. The comment is dropped too.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.23.0
    • addedInput schema / properties / challenge
      Added value: +{
      +  "description": "A challenge from ssh_key_challenge, exactly as issued (sshkc-…). Send it with signature, or leave both out. A challenge is not a credential: it is single-use and only for this person.",
      +  "type": "string"
      +}
    • addedInput schema / properties / signature
      Added value: +{
      +  "description": "The armored signature the challenge's sign_command printed, from -----BEGIN SSH SIGNATURE----- to -----END SSH SIGNATURE-----, made with this key. Send it with challenge, or leave both out.",
      +  "type": "string"
      +}
  2. First observedv0.13.1

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full behavioral burden and does so thoroughly: it discloses that the key is accepted only where SSH is enabled, is removed when the credential is revoked, can be replaced under the proof workflow, and has significant constraints on key format and ownership. These are exactly the behavioral details an agent needs before invoking a mutation tool.

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?

The description is front-loaded with the core action and uses a clear PROOF section for the complex conditional workflow. It is somewhat long and dense, but nearly every sentence carries operational constraints or behavioral detail that is not duplicated in the schema.

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?

For a tool with no annotations, no output schema, and a nontrivial proof-of-possession workflow, the description is complete enough for an agent to call it correctly. It covers inputs, constraints, refusal cases, and the follow-up challenge/signature process without relying on structured metadata for safety or behavior.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context beyond the schema by explaining the consequences of omitting `challenge` and `signature`, clarifying that an unproven key can only target a computer by id, and describing the proof replacement behavior.

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 description states a specific verb and resource: registering an OpenSSH public key for the person associated with the API key. It distinguishes this operation from the proof-related sibling `ssh_key_challenge` and from key removal by explaining the registration lifecycle and revocation behavior.

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?

It gives explicit accepted and refused key types, states the one-key-per-person and eight-key limits, warns against sending private keys, and explains the unproven/proven workflow with `ssh_key_challenge` as the necessary alternative. This is unusually clear guidance for when and how to use the tool.

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

Deploy Server

Other Tools