auth.mdx

December 13, 2025 · View on GitHub

Author(s): anna239

Elevator pitch

What are you proposing to change?

I suggest adding more information about auth methods that agent supports, which will allow clients to draw more appropriate UI.

Status quo

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

Agents have different ways of authenticating users: env vars with api keys, running a command like <agent_name> login, some just open a browser and use oauth. AuthMethod does not really tell the client what should be done to authenticate. This means we can't show the user a control for entering key if an aggent support auth through env var.

What we propose to do about it

What are you proposing to improve the situation?

We can add different types of AuthMethods, so that clients can show some UI for them. For example, this auth method

{
  "id": "123",
  "name": "OpenAI api key",
  "description": "Provide your key",
  "type": "envVar",
  "varName": "OPEN_AI_KEY"
}

would allow client to prompt user to enter a key, then client can provide this key to an agent via OPEN_AI_KEY env variable.

Shiny future

How will things will play out once this feature exists?

It will be easier for end-users to start using an agent from inside the IDE as auth process will be more straightforward

Implementation details and plan

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

I suggest adding following auth types:

  1. Env variable

A user can enter a key and a client will pass it to the agent as an env variable

{
  "id": "123",
  "name": "OpenAI api key",
  "description": "Provide your key",
  "type": "envVar",
  "varName": "OPEN_AI_KEY",
  "link": "OPTIONAL link to a page where user can get their key"
}
  1. Start argument

A user can enter a key, and a client will pass it to the agent as a start parameter

{
  "id": "123",
  "name": "OpenAI api key",
  "description": "Provide your key",
  "type": "startParam",
  "paramName": "OPEN_AI_KEY",
  "link": "OPTIONAL link to a page where user can get their key"
}
  1. Agent auth

Same as what there is now – agent handles the auth itself, this should be a default type if no type is provided for backward compatibility

{
  "id": "123",
  "name": "Agent",
  "description": "Authenticate through agent",
  "type": "agent"
}

To better handle oauth scenarios, we can add a mechanism like (MCP-elicitation)[https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation] User sends authenticate request with method id; then server calls an elicitation/create method on a client, that includes a link to an oauth provider and authenticateRequestId so that we can clearly link the request with the auth request.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "authenticateRequestId": "123",
    "url": "https://mcp.example.com/ui/set_api_key",
    "message": "Please provide your API key to continue."
  }
}

Client then allows user to open a browser and authenticate themselves. Agent then responds to an elicitation request with a key:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "action": "accept"
  }
}

and then responds to the original authenticate request.

  1. Provided key

User can enter the key and a client should pass it to the agent via AuthenticateRequest

{
  "id": "123",
  "name": "OpenAI api key",
  "description": "Provide your key",
  "type": "enterKey",
  "link": "OPTIONAL link to a page where user can get their key"
}

in this case AuthenticateRequest should also be updated. I suggest adding an optional authParams property

{
  "methodId": "123",
  "authParams": {
    "key": "...."
  }
}

This approach also requires adding a new elicitation client capability. If the client does not support this capability, agent MUST NOT return such an authMethod in the initialize response.

AuthErrors

It might be useful to include a list of AuthMethod ids to the AUTH_REQUIRED JsonRpc error. Why do we need this if they're already shared during initialize: All supported auth methods are shared during initialize. When user starts a session, they've already selected a model, which can narrow down a list of options.

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

What alternative approaches did you consider, and why did you settle on this one?

An alternative approach would be to include this information to an agent's declaration making it more static, see Registry RFD

There is also an alternative to adding a separate elicitation capability, which is to create a separate auth type for this. Then the client can decide themselves if they support it or not.

Revision history