MCP Server
Configure the Atmos Pro MCP server — install per client, OAuth flow, full tool catalog, security model, revocation.
This page covers how to install the Atmos Pro MCP server in each supported client, how the OAuth flow works under the hood, the full tool catalog, the security model, and how to revoke a client. For why you'd want this and what it changes about your remediation loop, see What MCP unlocks for your agent.
Claude Code
Pick whichever you prefer — they do the same thing. A browser opens for sign-in and consent on first use.
Option 1 — Claude CLI
claude mcp add --transport http atmos-pro https://atmos-pro.com/mcpor
Option 2 — Edit ~/.claude.json (global) or .mcp.json (per-project)
{
"mcpServers": {
"atmos-pro": {
"type": "http",
"url": "https://atmos-pro.com/mcp"
}
}
}If you'd rather drive the install entirely yourself, see the full install page — same component, plus an explanation of what each step does.
When you run
claude mcp add --transport http atmos-pro https://atmos-pro.com/mcp (or the equivalent for your client):- 1Discovery. The client fetches
https://atmos-pro.com/.well-known/oauth-authorization-serverto learn where to register and authorize. - 2Dynamic Client Registration. The client registers itself with the Atmos Pro OAuth issuer (RFC 7591). No pre-shared secrets, no manual app creation.
- 3Authorization. A browser opens to
atmos-pro.com/oauth/authorize. If you're not signed in, sign in with GitHub. - 4Consent. You pick the workspace this client should access and which scopes to grant. Defaults are read-only.
- 5Token exchange. The browser redirects back to the client; tokens are stored in your OS keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
- 6Use. The client can now call any tool you authorized. Each call is recorded in the audit log with
actor_type=mcp_client.
The token is bound to one workspace. To switch workspaces, re-authorize.
The catalog follows a REST-style primitive convention: every resource has a filterable
list_<noun> and a single-row get_<noun>. Status pivots (e.g., "failing instances", "pending approvals") are filter arguments on the broad list tool, not separate intent-named tools. Run tools/list against the MCP server to see the current registered set with full input schemas.| Tool | Description | Required permission |
|---|---|---|
list_repos | All GitHub repositories the workspace's Atmos Pro installation has access to. | Workspace membership |
get_repo | One connected repository's status + instance count by (owner, repo). | Workspace membership |
list_stacks | Distinct stacks across the workspace. statusFilter narrows to stacks containing failing instances. | Workspace membership |
get_stack | Aggregate counts and status breakdown for one stack. | Workspace membership |
list_components | Distinct components, optionally filtered by stack/repo. statusFilter narrows to components with failing instances. | Workspace membership |
get_component | Aggregate counts and status breakdown for one component. | Workspace membership |
list_commits | Commits that touched a component (deduped per sha), with PR linkage. | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_instances | Instances (component-deployed-to-stack) across the workspace. Filter with statusFilter: ['drifted','error'] for triage. | Workspace membership |
get_instance | One instance row by id, with drift status + last drift run + dashboardUrl. | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_workflow_runs | Workflow runs across the workspace. approvalState='pending' for awaiting approval; trigger='drift_detection' for drift runs; command='apply' + status=['in_progress'] for in-flight deployments; instanceId to scope to one instance. | Workspace membership |
get_workflow_run | One run with full diagnostic fields (status, conclusion, dispatchError, planExitCode, ref, sha, approval details, joined PR/changeRequest fields). | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_jobs | GitHub Actions jobs (with steps + conclusions) for one workflow run. Cheap navigation tool — call before get_workflow_run_logs so the agent can pick a jobName / stepName by string instead of guessing. | Workspace membership |
list_job_summaries | Each job's GitHub Job summary markdown (the $GITHUB_STEP_SUMMARY output, which Atmos workflows use to render the structured component-status table, drift counts, and plan diffs). Per-job 25KB cap with a truncated flag per entry. | Workspace membership |
get_workflow_run_logs | Raw GitHub Actions logs. Defaults to failedOnly:true, tailLines:200 (~10KB) for cheap triage; pass jobName + stepName to scope further. | Workspace membership |
explain_workflow_failure | Composes the dispatch + execution classifiers into a structured fix proposal: { category, description, suggestedAction: { type: rerun | fix_parent_run | fix_credentials | fix_ref | fix_code | approve | investigate, target, confidence }, parentRunId, planSawChanges }. The agent routes on suggestedAction.type instead of regex-matching prose. | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
get_repo_analytics | Per-repo metrics matching the dashboard's Analytics tab: workflow run counts (completed/failed), change failure rate, drift status counts, success rate by stack, PR merge-time stats, top contributors, and drift detection counts. Compares N-day window to prior period. | Workspace membership |
get_workspace_insights | Workspace-aggregate metrics matching the dashboard's Insights page (sidebar /insights). | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_deployments | Workflow runs with command IN ('apply','remediate') — i.e. deployments. Use limit:1 for the latest, component to scope. | Workspace membership |
get_deployment | One deployment row by id (a workflow_run with command IN ('apply','remediate')). | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_pull_requests | PRs across the workspace. component/stack filter via runs that touched the target. | Workspace membership |
get_pull_request | One PR by (owner/repo, number). | Workspace membership |
| Tool | Description | Required permission |
|---|---|---|
list_audit_log_entries | Workspace audit log entries with rich filters (action, actorType, since/until, target). | ws:audit_log:read |
get_audit_log_entry | One entry by id. | ws:audit_log:read |
| Tool | Description | Required permission |
|---|---|---|
list_permissions | Full Atmos Pro permission vocabulary, organized by resource. | None |
get_permission | Parsed structural info for one permission key (scope, group, action, isRecognized). | None |
list_my_permissions | The intersection of the user's role permissions and the token's granted scopes — what this token can actually do. | None |
list_permission_errors | Recent audit-log entries where an MCP client was denied access. Useful for diagnosing rejected tool calls. | ws:audit_log:read |
| Tool | Description | Required permission |
|---|---|---|
list_badge_types | Catalog of supported SVG badge types served by /api/badge with their parameter shapes. | None |
list_badge_tokens | Per-repo signed badge tokens with their live URLs. | Workspace membership |
render_badge | Render a badge to { url, markdown } for embedding in a README. | None |
| Tool | Description | Required permission |
|---|---|---|
get_workspace | Bound workspace info (id, name, slug, plan, status, repo + stack counts, dashboardUrl). | Workspace membership |
list_entitlements | Resolved entitlement vector as [{key, value, source}]. source distinguishes plan defaults from overrides. | Workspace membership |
list_egress_ips | Static list of Atmos Pro egress IPs for firewall allow-listing. | None |
list_repairs | "What's broken?" categories (connections, access, drift, failures) with severity + counts. | Workspace membership |
list_repair_connections | Repos with broken GitHub App installations (suspended, uninstalled). | Workspace membership |
get_setup_checklist | The 12-step setup checklist with achievement state + CTA hrefs. | ws:workspace:update_settings |
list_recommendations | Derived "what should I do next?" recommendations from workspace signals. | ws:workspace:update_settings |
Mutations (approve/reject runs, dispatch workflows, comment on PRs) ship in a follow-up release once the read-only surface stabilizes. They require a separate consent step in the browser.
- Tokens are opaque and stored as SHA-256 hashes — they cannot be reconstructed from the database.
- Tokens are short-lived. Access tokens expire in ≤1 hour. Refresh tokens last 30 days and rotate on every use; revoking one cascades to its entire rotation chain.
- Tokens are scoped. Effective permissions =
user_role_permissions ∩ token.scopes. Granting a token anupdatescope does not let it act beyond what the user themselves can do. - Destructive operations are unreachable. Workspace deletion, billing changes, webhook configuration, and repository deletion are blocked at the actor-type guard regardless of any scope claim.
- Every tool call is audited.
actor_type=mcp_client,client_id, redacted arguments, and the workspace are recorded in the audit log. Free-text fields (query,comment,body,description) are redacted by default. - Rate-limited. 600 requests/minute and 50,000 requests/day per token (configurable per workspace).
Open the dashboard, then
Settings → MCP Clients. You'll see one row per active client with last-used time, granted scopes, and number of active tokens. Click Revoke on any client to invalidate every token in its rotation chain immediately. The next request from that client will return 401.- What MCP unlocks for your agent — concepts and the MTTR loop