Agents

MCP setup

Atlas ships a local stdio MCP server for clients that want typed tools instead of a shell. It calls the same service layer as the CLI, so it is never a second source of truth: ticket and event mutations still run permission checks, the write lock, and attributed event metadata.

Start the server

tracker mcp serve --global --tool-profile workflow
tracker mcp tools --json --global --tool-profile workflow
tracker mcp serve --workspace /absolute/path/to/repo --tool-profile read
tracker mcp serve --workspace /absolute/path/to/existing-directory --tool-profile workflow --init-if-missing
tracker mcp schema --json --tool-profile workflow

tracker init registers detected clients as atlas-tasker with tracker mcp serve --global --tool-profile workflow. Restart the client; a written file is not a live connection. Grok also needs project trust before local skills appear. --global cannot be combined with --workspace or --init-if-missing. Cross-workspace writes need workspace_id. Both global and pinned serve default to --tool-profile workflow. Use --tool-profile read or --read-only for inspection only. Pinned serve reads the current directory unless --workspace names one. Without a pin, a user-scoped client starts wherever it happens to be, which is the usual reason a tool returns not_found for a ticket you can see in your terminal.

--init-if-missing is an explicit bootstrap opt-in for a fresh workspace. It requires an absolute path to an existing directory and a write-capable workflow, delivery, or admin profile. Atlas refuses the option with the read profile, --read-only, a nested Atlas root, or redirected initialization outputs. Bootstrap creates the first project and registers the workspace with Home without opening a browser or changing agent registrations. Existing projects and workspace identity are preserved. Use atlas.project.create with key and name for additional projects.

Profiles

Four cumulative profiles decide which tools exist in a session. Use read for inspection and workflow when the agent is expected to work tickets. Inspect your installed binary rather than assuming a count from documentation.

Grok Build

tracker init and tracker setup --yes --agents grok include --tool-name-style portable automatically. Grok receives names such as atlas_status and atlas_board; other clients keep dotted names such as atlas.status. The tools use the same handlers, permission checks, and response limits.

After setup, restart Grok and ask “How are the tickets looking?” Home’s Agents page shows the registration scope and actual command. A matching configuration can still need a client restart; successful tool use confirms the connection.

Client setup

Claude Code

claude mcp add --transport stdio --scope user atlas -- /absolute/path/to/tracker mcp serve --workspace /absolute/path/to/repo --tool-profile workflow

Keep --workspace explicit for project-scoped registrations too. Check status inside Claude Code with /mcp.

Codex

codex mcp add atlas -- /absolute/path/to/tracker mcp serve --workspace /absolute/path/to/repo --tool-profile workflow

# or in config.toml
[mcp_servers.atlas]
command = "/absolute/path/to/tracker"
args = ["mcp", "serve", "--workspace", "/absolute/path/to/repo", "--tool-profile", "workflow"]

Other MCP clients

Configure a local stdio server with an absolute binary path and argument array equivalent to mcp serve --workspace /absolute/path/to/repo --tool-profile workflow. Atlas does not claim a client-specific registration command unless that command is documented and tested by the client. Repository guidance installed by tracker integrations install is a separate step; it does not create this MCP registration.

Response budgets

Tool results are capped so a big board cannot flood a model's context. The defaults are 128 KB per result, 50 items per list, and a rough 4,000-token estimate for the text fallback. Tune them per server:

tracker mcp serve \
  --tool-profile read \
  --max-result-bytes 131072 \
  --max-items 50 \
  --max-text-tokens-estimate 4000

• Paged list tools accept limit and cursor, and payloads return total, next_cursor, and truncated.
• Grouped reads keep independent cursors: atlas.board takes cursor_by_status and atlas.dashboard takes cursor_by_section, so a short column never disappears because a long one advanced.
• Oversized results come back as a truncated summary with a hint to narrow the call instead of a silent cut.

What a tool call looks like

{
  "format_version": "v1",
  "kind": "atlas.ticket.view",
  "generated_at": "2026-05-05T12:00:00Z",
  "payload": {}
}

Every tool also declares the underlying_atlas_action it maps to and a json_schema_hash for its arguments, and calls are validated against that schema before they reach the tracker. Unknown arguments and wrong JSON types are rejected at the adapter boundary. Ticket and event mutations require explicit actor and reason arguments. The CLI resolves actor identity from its flag, environment, or config and requires reasons only for protected or security-sensitive actions, so do not infer MCP arguments from CLI optionality. atlas.project.create is the metadata-container exception: its closed schema accepts only key and name, and project creation writes no attributed event.