TeamServer Routes Required for MCP Server OAuth Support

This document lists all TeamServer API routes that the MCP server uses and would need to support OAuth2 bearer token authentication for the MCP server to be hosted publicly.

Applications & Application Data

• GET /ng/{orgId}/applications?base=false&expand=metadata,technologies,skip_links - List all applications
• GET /ng/{orgId}/applications/{appId}?expand=... - Get single application details
• GET /ng/{orgId}/applications/filter?... - Filter applications

Vulnerabilities (Assess)

• POST /ng/{orgId}/traces/{appId}/filter?expand=session_metadata,server_environments - Get traces/vulnerabilities for app
• POST /ng/{orgId}/orgtraces/filter/?expand=session_metadata,server_environments - Get traces across organization
• GET /ng/{orgId}/traces/{traceId}/recommendation - Get remediation recommendation
• GET /ng/{orgId}/traces/{traceId}/httprequest - Get HTTP request that triggered vulnerability
• GET /ng/{orgId}/traces/{traceId}/events/summary - Get event summary for trace
• GET /ng/{orgId}/traces/{traceId}/story - Get vulnerability story
• GET /ng/{orgId}/rules - Get vulnerability rules/types

Session Metadata

• GET /ng/{orgId}/metadata/session/{appId}/filters?modules={appId} - Get session metadata filters
• GET /ng/organizations/{orgId}/applications/{appId}/agent-sessions/latest - Get latest session metadata (custom route)

Libraries & SCA (Software Composition Analysis)

• GET /ng/{orgId}/applications/{appId}/libraries/filter?limit={n}&expand=vulns - Get libraries for application
• GET /ng/{orgId}/libraries/filter?... - Get libraries at org level
• GET /ng/organizations/{orgId}/cves/{cveId} - Get applications vulnerable to CVE (custom route)
• GET /ng/organizations/{orgId}/applications/{appId}/libraries/{libraryId}/reports/library-usage?offset={n}&limit={n}&sortBy=lastObservedTime&sortDirection=DESC - Get library observations (custom route)

Route Coverage

• GET /ng/{orgId}/applications/{appId}/route?sort=-exercised - Get route coverage
• POST /ng/{orgId}/applications/{appId}/route/filter?expand=observations - Get route coverage with metadata filter
• GET /ng/{orgId}/applications/{appId}/route/{routeHash}/observations?expand=skip_links,session_metadata - Get route details (custom route)

ADR/Protect (Attack Detection & Response)

• GET /ng/{orgId}/protection/policy/{appId}?expand=skip_links - Get protect/ADR rules (custom route)
• POST /ng/{orgId}/attacks?expand=skip_links&limit={n}&offset={n}&sort={sort} - Get attacks (custom route)

SAST (Static Analysis)

• Scan-related routes via scan manager (delegated to scan API gateway, likely separate from TeamServer OAuth)

Supporting Routes

• GET /ng/profile/organizations - Get user's organizations
• GET /ng/{orgId}/users?expand=login,signup - Get organization users
• GET /ng/global/properties - Get global properties

---

Summary by HTTP Method

GET Routes (26 total)

• Applications: 3 routes
• Vulnerabilities: 5 routes
• Session metadata: 2 routes
• Libraries/SCA: 2 routes
• Route coverage: 2 routes
• ADR/Protect: 1 route
• User/Org data: 3 routes
• Library observations: 1 route (custom)
• CVE data: 1 route (custom)
• Route details: 1 route (custom)
• Latest session: 1 route (custom)
• Protect policy: 1 route (custom)

POST Routes (4 total)

• Trace filtering: 2 routes (app-level and org-level)
• Route coverage with metadata: 1 route
• Attacks: 1 route (custom)

---

Priority Grouping for OAuth Implementation

High Priority (Core MCP Functionality)

These routes are essential for basic MCP server operation:

1. All vulnerability/trace routes (/ng/{orgId}/traces/*, /ng/{orgId}/orgtraces/*)
2. Application routes (/ng/{orgId}/applications/*)
3. Library routes (/ng/{orgId}/libraries/*, /ng/{orgId}/applications/{appId}/libraries/*)

Medium Priority (Enhanced Features)

These routes enable additional MCP server features:

4. Route coverage routes
5. Session metadata routes
6. ADR/Protect routes and attacks endpoint
7. Library observations and CVE routes

Lower Priority (Optional/Administrative)

These routes are less critical or may have alternative implementations:

8. User/org management routes
9. SAST scan routes (may use separate auth service)

---

Notes

• Custom routes are those not part of the standard Contrast SDK but implemented directly in the MCP server's SDKExtension class
• All routes currently use the legacy API key authentication (Authorization header with API key, service key, and username)
• For OAuth2 implementation, these routes would need to accept Authorization: Bearer {access_token} headers
• The MCP server makes requests to these endpoints on behalf of authenticated users
• RBAC (Role-Based Access Control) checks should remain in place after OAuth2 implementation

---

Implementation Considerations

Authentication Flow

When the MCP server is hosted publicly with OAuth2:

1. User authenticates via OAuth2 authorization code flow with PKCE
2. MCP server receives access token
3. MCP server includes access token in Authorization: Bearer {token} header for all TeamServer API requests
4. TeamServer validates the JWT token and extracts user identity
5. TeamServer applies existing RBAC checks based on user identity from token

JWT Token Requirements

The access token JWT should contain at minimum:

• userId - User ID for RBAC checks
• userUid - User email/identifier
• userName - Display name
• organizationMemberships - Organizations the user has access to
• Standard claims: iss, sub, aud, exp, iat, jti

Backwards Compatibility

The OAuth2 implementation should maintain backwards compatibility with existing API key authentication to avoid breaking existing integrations.