Authenticate with Atlassian's REST API using OAuth 2.0 (3LO) or a personal access token; Compass uses the same Atlassian identity as Jira and Confluence
Create a component via the Compass GraphQL API: POST to https://api.atlassian.com/graphql with a compassCreateComponent mutation specifying name, type (SERVICE, LIBRARY, APPLICATION, etc.), and cloudId
Attach a scorecard to the component: use the compassApplyScorecardToComponent mutation with the scorecard ID (retrieved from compassScorecard query) and the component ID
Define scorecard criteria: scorecards consist of criteria with weights summing to 100%; criteria are configured in the Compass UI or via mutation; custom metrics can be pushed via compassUpdateMetric mutation
Push a metric value: use the compassUpdateMetricDefinitionValue mutation to report a numeric metric (e.g., deployment frequency, test coverage) that a scorecard criterion evaluates against a threshold
Query component health: compassComponent query returns currentScore and appliedScorecards.criteria[].passing to report which criteria are met or failing
Known gotchas
Atlassian announced in 2025 that Compass scorecard and catalog functionality will transition to the Atlassian DX app; verify current API stability and whether new development should target the DX app or Compass APIs
The cloudId is required for all Compass API operations and is tied to your Atlassian cloud site; retrieve it from GET https://api.atlassian.com/oauth/token/accessible-resources after OAuth authorization
Compass uses GraphQL exclusively for programmatic management; there is no equivalent REST API for most operations — familiarity with GraphQL mutations and fragments is required
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp