Standardize MCP Server Response Format to JSON

[aravinder111]

New issue?

• I have reviewed the Existing Issues and confirm this is not an existing issue.

Bug

The Okta MCP server returns inconsistent response formats that make it difficult for clients to parse responses reliably. Currently, responses are returned as:

1. Python dict strings instead of JSON strings (most common)
2. Enum objects embedded in the response strings instead of their string values
3. Unparseable object string representations for some tools (e.g., get_user)
4. Tuples in list responses instead of proper dictionaries
5. Mixed formats across different tools

This inconsistency forces clients to implement complex parsing logic with multiple fallback strategies, which is error-prone and not maintainable.

Expected behavior

All MCP server responses should follow the MCP protocol standard and return JSON strings in the content[].text field:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\": \"0oa123\", \"name\": \"My App\", \"status\": \"ACTIVE\", \"sign_on_mode\": \"SAML_2_0\"}"
      }
    ],
    "isError": false
  }
}

Key requirements:

1. JSON format: All responses should be valid JSON strings (not Python dict strings)
2. Enum values: Enum objects should be serialized to their string values (e.g., "SAML_2_0" instead of <ApplicationSignOnMode.SAML_2_0: 'SAML_2_0'>)
3. Proper serialization: Objects like OktaAPIResponse should be serialized to JSON, not converted to string representations
4. Consistent structure: List responses should return arrays of objects, not tuples
5. Standard types: All values should be JSON-serializable (strings, numbers, booleans, null, objects, arrays)

Observed behavior

Current Behavior

Example 1: Python Dict String with Enum Objects

Tool: get_application or list_applications

Response:

"{'id': '0oa123', 'name': 'My App', 'status': 'ACTIVE', 'sign_on_mode': <ApplicationSignOnMode.SAML_2_0: 'SAML_2_0'>}"

Issues:

• Python dict string format (not JSON)
• Enum object (<ApplicationSignOnMode.SAML_2_0: 'SAML_2_0'>) cannot be parsed by standard JSON parsers
• Requires ast.literal_eval() and custom enum handling

Example 2: Unparseable Object String

Tool: get_user

Response:

"<okta.api_response.OktaAPIResponse object at 0xffff8132b770>"

Issues:

• Completely unparseable - no data can be extracted
• This appears to be a serialization bug where the object is converted to its string representation instead of being properly serialized

Example 3: Tuples in List Responses

Tool: list_users

Response:

{
  "items": [
    ("{'email': 'user@example.com', 'firstName': 'John', ...}", "00u123"),
    ("{'email': 'user2@example.com', 'firstName': 'Jane', ...}", "00u456")
  ],
  "total_fetched": 2
}

Issues:

• Items are tuples instead of dictionaries
• First element of tuple is a Python dict string, not JSON
• Requires special handling for tuple unpacking

Relevant log output

Additional information

Affected Tools

Based on testing, the following tools are affected:

• get_application - Returns Python dict string with enum objects
• list_applications - Returns Python dict string with enum objects
• get_user - Returns unparseable object string representation
• list_users - Returns tuples instead of objects
• get_group - Returns Python dict string
• list_groups - Returns Python dict strings in items array
• Likely affects all 40+ tools in the server

MCP Protocol Compliance

The Model Context Protocol specification expects responses to be JSON-serializable. The current implementation violates this expectation by returning Python-specific formats (dict strings, enum objects, tuples).

Requested Action

Please standardize all MCP server responses to:

1. Return valid JSON strings in the content[].text field
2. Serialize enum objects to their string values
3. Fix object serialization issues (especially get_user)
4. Ensure consistent format across all tools
5. Add validation to prevent regression

This will make the Okta MCP server compliant with MCP standards and much easier for clients to integrate.

Additional Context

• MCP Protocol: https://modelcontextprotocol.io
• Current workaround: Clients must implement multi-strategy parsing with ast.literal_eval() and custom enum handling
• Impact: Affects all clients integrating with the Okta MCP server