Add positive tests for the Authorization Code Grant

[Michito-Okai]

Background

The MCP specification 2025-11-25 adheres to the Authorization Code Grant in OAuth 2.1. Therefore, conformance tests for authorization servers must verify whether the authorization server correctly implements the Authorization Code Grant.

First Step

As a first step, this issue focuses on implementing positive test cases for the Authorization Code Grant.

Specification References

• OAuth 2.1
• MCP Authorization Specification

Key Requirements from Specification

Authorization Response

Keyword	Statement
MUST	The URI in the authorization response MUST match the redirect_uri parameter in the authorization request
MUST	The code parameter MUST be present in the authorization response query parameters
MUST	The code parameter MUST have a value
MUST	The state parameter MUST match the state parameter in the authorization request query parameters if the state parameter is present in the authorization request query parameters
MUST	The iss parameter MUST match the issuer claim of authorization server metadata if the iss parameter is present in the authorization response query parameters
MUST	The code, state and iss parameters MUST NOT appear more than once
MUST	The code_challenge parameter MUST NOT be present in the authorization response query parameters
MUST	The error parameter MUST NOT be present in the authorization response query parameters

Token Response

Keyword	Statement
MUST	HTTP response status code of token response MUST be 200 OK
MUST	Content-Type header of token response MUST be application/json
MUST	Cache-Control header of token response MUST be no-store
MUST	Token response MUST return a JSON object including access_token and token_type

Approach

Authorization Code Grant tests for the authorization response output an authorization request URL to the console and start callback server. Testers access the output URL in their browser and complete the authentication process. Then, callback server receives a authorization response and validate it. Authorization Code Grant tests for the token response are direct HTTP probes. These tests send a POST request to the token endpoint and validate the response.
These require:

0. A tester set an authorization server to a client
1. An authorization CLI command that accepts --url <authorization-server-issuer-url> --client-id <client-id> --secret <client-secret> --port <callback server port> (e.g., --url https://auth.example.com --client-id test-client --secret MlAbxvNDZNnsZ67Ie6KENtzpA5mTh3ZK --port 3000)
2. A new runner (runner/authorization-code-grant.ts) for executing these scenarios
3. The scenario creates an authorization request, starts callback server
4. A tester sends the authorization request in their browser and completes the authentication process
5. Callback server receives an authorization response and the scenario validates the authorization response
6. The scenario sends a token request with client_secret_port, and validates the token response

Suggested Checks

Check: authorization-response

Spec: "The response is a URL."

Receive an authorization response from a tester → validate:

• URL matches the redirect_uri parameter
• The code parameter is present
• The code parameter has a value
• The state parameter in the authorization response query parameters matches the state parameter in the authorization request query parameters
• The iss parameter matches the issuer claim of authorization server metadata if present
• The code_challenge parameter is not present
• The error parameter is not present

Check: token-response

Spec: "The response is a JSON object... The authorization server MUST return HTTP 200 with Content-Type application/json."

Send POST request to the token endpoint → validate:

• HTTP 200 status code
• Content-Type: application/json
• Cache-Control: no-store
• Body is valid JSON containing access_token, token_type

Scenarios to Cover

Positive Tests for Authorization Response

1. URL matches the redirect_uri parameter
2. The code parameter is present
3. The state parameter matches the state parameter in the authorization response query parameters
4. The iss parameter matches the issuer claim of authorization server metadata if present
5. code_challenge and error parameters are not present

Negative Tests for Authorization Response

1. An authorization server returns an error to tester's browser → callback server timeout (5min) → FAILURE
2. URL is incorrect → FAILURE
3. code is not present → FAILURE
4. state and iss are incorrect → FAILURE
5. code, state and iss parameters appear more than once → FAILURE
6. code_challenge or error parameters are present → FAILURE

Positive Tests for Token Response

1. Token endpoint returns HTTP 200 with correct Content-Type
2. Cache-Control header is set to no-store
3. Response body contains all required fields (access_token, token_type)

Negative Tests for Token Response

1. Endpoint returns non-200 status code → FAILURE
2. Endpoint returns non-JSON content type → FAILURE
3. Response headers are not set correctly → FAILURE
4. Response body missing required fields → FAILURE

Implementation Notes

New Files

• src/scenarios/authorization-server/authorization-code-grant.ts — Scenario implementation
• src/scenarios/authorization-server/authorization-code-grant.test.ts — Unit tests
• src/scenarios/client/auth/helpers/createCallbackServer.ts — Callback server implementation

Modified Files

• src/runner/authorization-server.ts — Add metadata response body and secret to arguments
• src/scenarios/authorization-server/authorization-server-metadata.ts — Add metadata response body and secret to arguments
• src/scenarios/authorization-server/authorization-server-metadata.test.ts — Add metadata response body and secret to arguments
• src/types.ts — Modify arguments
• src/schemas.ts — Add clientId, secret, port command option
• src/scenarios/index.ts — Register the new scenario
• src/index.ts — Add clientId, secret, port command option and metadata response body to arguments

Patterns to Follow

• Validation for authorization response should fail fast: authorization code check
• Validation for token response should fail fast: status code, parse JSON, no body

To do

• Automation of launching the tester's browser and sending authorization requests
• Documentation of options for running MCP authorization server Conformance Tests
• Documentation of the settings that should be pre-registered in the MCP authorization server

[Michito-Okai]

@pcarleton Hello, if the issue makes sense, could you assign me to the issue? I cannot assign myself to the issue.

[nbarbettini]

@Michito-Okai We need to get #105 merged in. It is not the same thing as what you want to test here (testing the RS with a mocked/fake AS in #105 vs. testing the AS itself here), but I think it would give you some of the harness mechanics you need for this. What do you think?

[Michito-Okai]

@nbarbettini Thank you very much. I think that #105, including oauth-client.ts, cloud be used to implement a fake client.
Should I wait until #105 is merged, or should I extract the parts I need from #105 for this positive tests? What do you think?

[tnorimat]

@nbarbettini @Michito-Okai Hello, I prefer the option "extracting the parts from #105" because if waiting for #105 being merged, the work for the issue cannot go forward now.

[nbarbettini]

@Michito-Okai @tnorimat I hope to merge #105 soon, but in the meantime I agree it makes sense to extract what you need so you are not blocked. Good plan!

[Michito-Okai]

@pcarleton @nbarbettini @tnorimat
I updated this thread and submitted PR.
Could you please check them.