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

Token Response

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
• Add client_secret_jwt, private_key_jwt, tls_client_auth
• Documentation of options for running MCP authorization server Conformance Tests
• Documentation of the settings that should be pre-registered in the MCP authorization server