Agent Authentication State Query

• Author(s): @xtmq
• Champion: @benbrandt

​

Elevator pitch

What are you proposing to change?

​

Status quo

How do things work today and what problems does this cause? Why would we change things?

1. Call initialize
2. Call session/new
3. If the agent has no credentials, it may return an authorization error
4. The client handles the error and initiates an authorization flow

• Unreliable detection: The session/new method is not required by the specification to check authorization. Some agents validate credentials eagerly, others do so lazily (e.g., on the first LLM call). The client cannot rely on session/new to consistently surface auth issues.
• Wasted resources: Creating a session only to discard it on auth failure is wasteful, especially if session creation has side effects (resource allocation, logging, history file creation, etc.).
• Poor user experience: The client cannot proactively guide the user through authorization before session creation. Instead, users encounter errors mid-flow.

​

Shiny future

How will things play out once this feature exists?

1. Discover whether an agent supports auth state queries via capabilities during initialization
2. Query the agent’s current authentication state immediately after initialization
3. Make an informed decision about whether to proceed with session creation, initiate an authorization flow, or configure endpoints (e.g., via setLlmEndpoints)
4. Provide clear, proactive UX — e.g., showing a “Sign in” prompt before any session is created
5. Completely skip authentication process if the agent is already authenticated

​

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

​

Intended flow

1. Initialization: The client calls initialize. The agent responds with capabilities, including auth/status support via agentCapabilities.auth.
2. Auth state query: The client calls auth/status. The agent inspects its local configuration, stored credentials, or environment to determine the current auth state.
3. Client-side decision: Based on the response, the client either proceeds to session creation or initiates an authorization flow first.

​

Capability advertisement

interface AuthCapabilities {
  // ... existing fields (e.g., terminal) ...

  /**
   * Auth status query support.
   * If true, the agent supports the auth/status method.
   */
  status?: boolean;
}

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentInfo": {
      "name": "MyAgent",
      "version": "2.0.0"
    },
    "agentCapabilities": {
      "auth": {
        "status": true
      },
      "sessionCapabilities": {}
    }
  }
}

​

auth/status method

interface AuthStatusRequest {
  /** Extension metadata */
  _meta?: Record<string, unknown>;
}

interface AuthStatusResponse {
  /**
   * Whether the agent has credentials configured.
   * true means credentials are present (validity is not guaranteed).
   * false means no credentials are configured.
   */
  authenticated: boolean;

  /** Human-readable description of the overall auth state */
  message?: string;

  /** Extension metadata */
  _meta?: Record<string, unknown>;
}

​

JSON Schema Additions

{
  "$defs": {
    "AuthStatusResponse": {
      "description": "Response to auth/status method.",
      "properties": {
        "authenticated": {
          "type": "boolean",
          "description": "Whether the agent has credentials configured."
        },
        "message": {
          "type": ["string", "null"],
          "description": "Human-readable description of the overall auth state."
        },
        "_meta": {
          "additionalProperties": true,
          "type": ["object", "null"]
        }
      },
      "required": ["authenticated"],
      "type": "object"
    }
  }
}

​

Example Exchange

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "auth/status",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "authenticated": true,
    "message": "Credentials are configured"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "authenticated": false,
    "message": "No credentials configured. Please provide API keys or configure an LLM endpoint."
  }
}

​

Behavior

1. Capability advertisement: The agent SHOULD include auth.status in agentCapabilities if it supports the auth/status method. Clients MUST check for this capability before calling the method.
2. Timing: The auth/status method MUST be callable after initialize. It MAY be called multiple times (e.g., after authenticate, to re-check state).
3. Local checks only: The agent MAY determine auth state based on locally available information (config files, environment variables, stored tokens) or by making external API calls. authenticated: true means credentials are present, NOT that they are guaranteed to be valid.
4. No side effects: Calling auth/status MUST NOT modify any agent state. It is a pure query.
5. Aggregate response: The response includes only top-level authenticated and optional message, keeping the API surface minimal and avoiding per-method complexity.

​

Frequently asked questions

What questions have arisen over the course of authoring this document?

​

Why not rely on session/new errors?

​

Why not include auth state in the initialize response directly?

​

Why not just check for the presence of environment variables on the client side?

​

Why did we remove additional auth details from auth/status for now?

​

Revision history

• 2026-07-21: Accepted as a Draft RFD
• 2026-03-15: Remove authMethods from the proposal and keep aggregate auth state only (authenticated + optional message)
• 2026-03-10: Rename getAuthState to auth/status, nest capability under agentCapabilities.auth
• 2026-03-07: Address review feedback on auth state structure
• 2026-03-05: Initial draft — preliminary proposal to start discussion