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
Stored in ~/.claude.json under this project. Not shared, not committed.
claude mcp add --transport http atmos-pro https://qa-3.atmos-pro.com/mcpor
Option 2 — Edit ~/.claude.json (user scope) or .mcp.json (project scope)
{
"mcpServers": {
"atmos-pro": {
"type": "http",
"url": "https://qa-3.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. Scope-less requests default to read-only; action scopes such as
ws:instances:remediate_driftmust be requested and granted explicitly. - 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 |
|---|---|---|
search_documentation | Search published Atmos Pro documentation by topic and return agent-friendly Markdown context. | None |
list_documentation_pages | List published docs metadata, optionally filtered by query or section. | None |
get_documentation_page | Fetch one public docs page or section as efficient Markdown. Accepts slugs, /docs URLs, and docs:// URIs. | None |
Published docs are also available through MCP resources at
docs://atmos-pro/{slug} and public Markdown endpoints
such as /docs/configure/mcp.md, /docs/sitemap.md, and /docs/llms.txt.| 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 |
remediate_drift | Dispatches the configured Atmos Pro remediation workflow for a visible instance. Call get_instance first to confirm the target. | ws:instances:remediate_drift |
| 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 |
list_repository_labels | A repo's defined labels (pick valid ones before setting PR labels). | ws:pull_requests:read |
create_pull_request | Open a PR with file changes (verified commit). Defaults body to PULL_REQUEST_TEMPLATE.md, reviewer to the caller; pass base to stack on another PR. Returns not_imported (with a link) if the repo isn't imported. | ws:pull_requests:write |
update_pull_request | Edit the title/description of a PR Atmos Pro opened. | ws:pull_requests:write |
close_pull_request | Close a PR Atmos Pro opened (does not merge). | ws:pull_requests:write |
update_pull_request_branch | Bring a PR's branch up to date with base ("Update branch"; a merge, not a rebase). | ws:pull_requests:write |
request_pull_request_review | (Re-)request reviewers on a PR Atmos Pro opened. | ws:pull_requests:write |
set_pull_request_draft | Mark a PR ready-for-review or convert it back to draft. | ws:pull_requests:write |
set_pull_request_labels | Replace the labels on a PR Atmos Pro opened. | ws:pull_requests:write |
The write tools only act on PRs Atmos Pro itself opened — they refuse (
not_managed) any other PR.| 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 |
get_workspace_settings | Per-workspace admin feature toggles (stsEnabled, githubChatopsEnabled) from Settings → Security. Pair with list_entitlements for the plan gate. | 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 |
Additional mutations (approve/reject runs, dispatch arbitrary workflows, comment on PRs) ship in a follow-up
release once the scoped action surface stabilizes.
remediate_drift is available now and requires explicit consent
for ws:instances:remediate_drift.- 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