From c598aa181c8600e60d82a925dc4d1f7987b9ed24 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Thu, 11 Dec 2025 06:42:41 +0100 Subject: [PATCH 1/6] Add Authentication RFD --- docs/rfds/auth.mdx | 131 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 docs/rfds/auth.mdx diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx new file mode 100644 index 0000000..01c78fb --- /dev/null +++ b/docs/rfds/auth.mdx @@ -0,0 +1,131 @@ +--- +title: "AUTHENTICATION" +--- + +Author(s): [anna239](https://github.com/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 ` login`, some just open a browser and use oauth. +[AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can't show 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 +```json +{ + "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 + +```json +{ + "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" +} +``` + +2. Start argument + +A user can enter a key and a client will pass it to the agent as a start parameter + +```json +{ + "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" +} +``` + +3. Agent auth + +Same as what there is now -- agent handles the auth itself, this should be default type if no type is provided for backward compatibility + +```json +{ + "id": "123", + "name": "Agent", + "description": "Authenticate through agent", + "type": "agent" +} +``` + +4. Provided key + +User can enter the key and client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) + +```json +{ + "id": "123", + "name": "OpenAI api key", + "description": "Provide your key", + "type": "enterKey", + "link": "OPTIONAL link to a page where user can get their key" +} +``` + +for this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) should also be updated. I suggest adding optional authParams property + +```json +{ + "methodId": "123", + "authParams": { + "key": "...." + } +} +``` + +### 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? + +Alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289) + +## Revision history + + From ba68e705969b71fea63ab316847d7467d5ba0772 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Thu, 11 Dec 2025 06:46:09 +0100 Subject: [PATCH 2/6] fix formating --- docs/rfds/auth.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx index 01c78fb..000cbdc 100644 --- a/docs/rfds/auth.mdx +++ b/docs/rfds/auth.mdx @@ -22,6 +22,7 @@ Agents have different ways of authenticating users: env vars with api keys, runn > 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 + ```json { "id": "123", @@ -31,6 +32,7 @@ We can add different types of AuthMethods, so that clients can show some UI for "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 @@ -55,7 +57,7 @@ A user can enter a key and a client will pass it to the agent as an env variable "name": "OpenAI api key", "description": "Provide your key", "type": "envVar", - "varName": "OPEN_AI_KEY" , + "varName": "OPEN_AI_KEY", "link": "OPTIONAL link to a page where user can get their key" } ``` @@ -70,7 +72,7 @@ A user can enter a key and a client will pass it to the agent as a start paramet "name": "OpenAI api key", "description": "Provide your key", "type": "startParam", - "paramName": "OPEN_AI_KEY" , + "paramName": "OPEN_AI_KEY", "link": "OPTIONAL link to a page where user can get their key" } ``` From 048526c5ff20b896593bd2fc64704354ad305f94 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Sat, 13 Dec 2025 20:22:52 +0100 Subject: [PATCH 3/6] Add suggestion for MCP-like elicitation approach for oauth authnetication --- docs/rfds/auth.mdx | 47 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx index 000cbdc..a0b07b9 100644 --- a/docs/rfds/auth.mdx +++ b/docs/rfds/auth.mdx @@ -15,7 +15,7 @@ I suggest adding more information about auth methods that agent supports, which > 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 ` login`, some just open a browser and use oauth. -[AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can't show user a control for entering key if an aggent support auth through env var. +[AuthMethod](https://agentclientprotocol.com/protocol/schema#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 @@ -64,7 +64,7 @@ A user can enter a key and a client will pass it to the agent as an env variable 2. Start argument -A user can enter a key and a client will pass it to the agent as a start parameter +A user can enter a key, and a client will pass it to the agent as a start parameter ```json { @@ -79,7 +79,7 @@ A user can enter a key and a client will pass it to the agent as a start paramet 3. Agent auth -Same as what there is now -- agent handles the auth itself, this should be default type if no type is provided for backward compatibility +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 ```json { @@ -90,9 +90,40 @@ Same as what there is now -- agent handles the auth itself, this should be defau } ``` +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. + +```json +{ + "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: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "action": "accept" + } +} +``` + +and then responds to the original `authenticate` request. + + 4. Provided key -User can enter the key and client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) +User can enter the key and a client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) ```json { @@ -104,7 +135,7 @@ User can enter the key and client should pass it to the agent via [AuthenticateR } ``` -for this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) should also be updated. I suggest adding optional authParams property +in this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) should also be updated. I suggest adding an optional authParams property ```json { @@ -115,6 +146,8 @@ for this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/sch } ``` +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`: @@ -126,7 +159,9 @@ All supported auth methods are shared during `initialize`. When user starts a se ### What alternative approaches did you consider, and why did you settle on this one? -Alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289) +An alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289) + +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 From 939ef116a1b14016e4e3808b8764237250afa253 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Sat, 13 Dec 2025 20:26:05 +0100 Subject: [PATCH 4/6] Add suggestion for MCP-like elicitation approach for oauth authnetication --- docs/rfds/auth.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx index a0b07b9..24306a3 100644 --- a/docs/rfds/auth.mdx +++ b/docs/rfds/auth.mdx @@ -120,7 +120,6 @@ Client then allows user to open a browser and authenticate themselves. Agent the and then responds to the original `authenticate` request. - 4. Provided key User can enter the key and a client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) From 3f57ae7b029a1880064e9c4f323db14ff8a63653 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Tue, 23 Dec 2025 15:58:06 +0100 Subject: [PATCH 5/6] Update auth rfd --- docs/rfds/auth.mdx | 77 ++++++++++++++++------------------------------ 1 file changed, 26 insertions(+), 51 deletions(-) diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx index 24306a3..92c1250 100644 --- a/docs/rfds/auth.mdx +++ b/docs/rfds/auth.mdx @@ -58,7 +58,8 @@ A user can enter a key and a client will pass it to the agent as an env variable "description": "Provide your key", "type": "envVar", "varName": "OPEN_AI_KEY", - "link": "OPTIONAL link to a page where user can get their key" + "link": "OPTIONAL link to a page where user can get their key", + "requiresRestart": true // default } ``` @@ -73,7 +74,8 @@ A user can enter a key, and a client will pass it to the agent as a start parame "description": "Provide your key", "type": "startParam", "paramName": "OPEN_AI_KEY", - "link": "OPTIONAL link to a page where user can get their key" + "link": "OPTIONAL link to a page where user can get their key", + "requiresRestart": true // default } ``` @@ -86,72 +88,43 @@ Same as what there is now – agent handles the auth itself, this should be a de "id": "123", "name": "Agent", "description": "Authenticate through agent", - "type": "agent" + "type": "agent", + "requiresRestart": false // default, can be changed } ``` -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. +4. Terminal auth -```json -{ - "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: - -```json -{ - "jsonrpc": "2.0", - "id": 3, - "result": { - "action": "accept" - } -} -``` - -and then responds to the original `authenticate` request. - -4. Provided key - -User can enter the key and a client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) +What's now done with `terminal-auth` capability and _meta field, for backward compatibility clients might want to read properties from both _meta and the object itself. +This means that the client should run the provided command themselves in the terminal and let user interact with that terminal ```json { "id": "123", - "name": "OpenAI api key", - "description": "Provide your key", - "type": "enterKey", - "link": "OPTIONAL link to a page where user can get their key" + "name": "Run in terminal", + "type": "terminal", + "command": "/path/to/command", + "args": ["--setup"], + "env": {"VAR1": "value1", "VAR2": "value2"}, + "label": "Setup Label", + "requiresRestart": true // default, can be changed } -``` -in this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) should also be updated. I suggest adding an optional authParams property - -```json -{ - "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. +```json +{ + "jsonrpc":"2.0", + "id":2, + "error":{"code":-32000,"message":"Authentication required", "authMethods":[{"id":"chatgpt","name":"Login with ChatGPT","description":"Use your ChatGPT login with Codex CLI (requires a paid ChatGPT subscription)"}]} +} +``` + ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? @@ -165,3 +138,5 @@ There is also an alternative to adding a separate `elicitation` capability, whic ## Revision history + +There was a part about elicitations https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx removed it for now, will move to a separate rfd \ No newline at end of file From 4bba4eb0e76427a605d21d4d495f4b5f42ac97fc Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Tue, 23 Dec 2025 16:08:55 +0100 Subject: [PATCH 6/6] fix formatting --- docs/rfds/auth.mdx | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx index 92c1250..f3db45b 100644 --- a/docs/rfds/auth.mdx +++ b/docs/rfds/auth.mdx @@ -95,7 +95,7 @@ Same as what there is now – agent handles the auth itself, this should be a de 4. Terminal auth -What's now done with `terminal-auth` capability and _meta field, for backward compatibility clients might want to read properties from both _meta and the object itself. +What's now done with `terminal-auth` capability and \_meta field, for backward compatibility clients might want to read properties from both \_meta and the object itself. This means that the client should run the provided command themselves in the terminal and let user interact with that terminal ```json @@ -105,11 +105,10 @@ This means that the client should run the provided command themselves in the ter "type": "terminal", "command": "/path/to/command", "args": ["--setup"], - "env": {"VAR1": "value1", "VAR2": "value2"}, + "env": { "VAR1": "value1", "VAR2": "value2" }, "label": "Setup Label", "requiresRestart": true // default, can be changed } - ``` ### AuthErrors @@ -119,9 +118,19 @@ All supported auth methods are shared during `initialize`. When user starts a se ```json { - "jsonrpc":"2.0", - "id":2, - "error":{"code":-32000,"message":"Authentication required", "authMethods":[{"id":"chatgpt","name":"Login with ChatGPT","description":"Use your ChatGPT login with Codex CLI (requires a paid ChatGPT subscription)"}]} + "jsonrpc": "2.0", + "id": 2, + "error": { + "code": -32000, + "message": "Authentication required", + "authMethods": [ + { + "id": "chatgpt", + "name": "Login with ChatGPT", + "description": "Use your ChatGPT login with Codex CLI (requires a paid ChatGPT subscription)" + } + ] + } } ``` @@ -139,4 +148,4 @@ There is also an alternative to adding a separate `elicitation` capability, whic -There was a part about elicitations https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx removed it for now, will move to a separate rfd \ No newline at end of file +There was a part about elicitations https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx removed it for now, will move to a separate rfd