# ogma workspace portal > The signed-in front door of the ogma workspace suite: the tabbed Home > (a pane per app), the Home dashboard (a tab per board), federated > search, /profile (including API token minting) and the consolidated /admin. > It holds no data of its own — and it hosts the platform's MCP gateway. > All paths below are relative to this host. ## MCP gateway (`/mcp`) One Model Context Protocol endpoint for the whole workspace — boards, git repositories and chat as tools for LLM clients (Claude Code, Claude Desktop, the platform's own agents, anything speaking MCP). - **Transport**: streamable HTTP, stateless, JSON responses. No sessions, no SSE — every POST is self-contained. - **Skills**: the gateway declares the `io.modelcontextprotocol/skills` extension (SEP-2640) and serves two skills — `ogma`, the conventions that make these tools usable, and `ogma-fleet`, the extra rules for a bot account working a board's queue. See [Skills](#skills-sep-2640) below. - **Auth**: `Authorization: Bearer ` on every request. Tokens are minted on this host (Profile → API tokens). The gateway forwards your token to the owning app, so its scopes (`projects:*`, `repos:*`, `chat:*`) and your own memberships decide what each tool may do — denials come back as readable tool errors. - **Claude Code**: claude mcp add --transport http ogma https:///mcp \ --header "Authorization: Bearer " - **OAuth clients** (Claude Desktop / claude.ai custom connectors — no bearer-header field there): add `https:///mcp` as a custom connector with **client id `ogma`** and **your API token as the client secret** (Advanced settings). The OAuth shim validates the secret against the auth service and hands it back as the access token — same credential, same scopes, no separate grant to manage. Revoking the API token disconnects the connector. - **Tools** (namespaced by app; outputs are the apps' documented JSON — see each app's own /llms.txt for shapes): - `whoami` — the key's owner (id, email, display name, platform role). - **Boards** — `projects_list` (boards you can see; `include_archived` widens it to archived ones), `projects_create` (a furnished board: six columns, eight labels, the priority ladder), `projects_update` (rename / describe / re-point the repository; no delete), `projects_archive` (file a board away or put it back — the reversible way to dispose of one you created; deleting a board is deliberately not offered, destruction stays a human act), `projects_members` (the valid assignees), `projects_member_add` (by email; an address with no account becomes a pending invitation), `projects_member_remove` (by user id). - **Columns** — `projects_board` (columns with their cards — where card ids, column ids, positions and each card's `number` come from), `projects_columns` (columns only, with `counts_as_done`; `with_cards` for the full board), `projects_column_create`, `projects_column_update` (rename, reorder, `counts_as_done`, `gated`, and with agents on its `hat_id` and `specialists_only`), `projects_column_delete` (deletes every card in it). - **Cards** — `projects_card` (one card in full, with its `guide`: your part on the card, its hat, its Story, what is needed now and the rules for working it, in order), `projects_card_create` (`owner_type: "agent"` for fleet work), `projects_card_update` (PATCH semantics), `projects_card_unassign`, `projects_card_move` (a gated destination refuses with the gate's criteria listed), `projects_card_archive` (file a card away or put it back — the reversible way to dispose of finished business; the card leaves every board and search but still answers to `projects_card` by id, and checklist items tracking it go withdrawn; deleting a card is deliberately not offered), and the bulk forms `projects_cards_create`, `projects_cards_update`, `projects_cards_move`, `projects_cards_label`, `projects_cards_unlabel` (independent per card; they report `{requested, succeeded, failed, ok, errors}`). Cards carry `number`, the per-board human handle ("card #12") — resolve it via `projects_board`; tool arguments always take ids. Cards embed applied labels as `labels: [{id, name, color}]`. - **Agent work** — `projects_card_claim` (atomic compare-and-swap; 409 if held, human-owned, or over the WIP cap), `projects_card_release`, `projects_claim_next` (the head of the board's ready queue, which starts at the board's intake column — nothing left of it is offered — priority, then a leaf of an epic already under way, then number; WIP-aware; passes over a card whose only open checklist items are reference pills — waiting, not ready), `projects_attention` (stamp what you are looking at; ~45 s heartbeats), `projects_finding` (a 1–280 char observation / decision / blocker / result), `projects_plan_publish` (plan as a durable comment, optionally a checklist), `projects_card_decompose` (child agent cards tracked by checklist refs), `projects_card_handoff` (handoff comment + release; holder only), `projects_card_rollback` (a person's undo of a takeover: the card back to the snapshot, comments since retracted, branch reset; refused while held or over a person's edits unless `force`), `projects_rot_report` (stale claimed cards: `rot` / `silence`; read-only), `projects_card_story` (write the card's Story: `purpose`, `progress`, `next` — one plain sentence each), `projects_instruction_done` (mark an instruction in the card's room done). A claim answers with the card's `hat`, `room_id` and `guide`. - **Gates** — `projects_card_gate` (what the card must satisfy per gated column, and what is acked), `projects_card_gate_ack` (one criterion per call; evidence where required; no bulk, no force), `projects_card_gate_unack`, `projects_gate_criteria` (the board's criteria by scope), `projects_gate_criterion_create` (column-, card- or board-scoped), `projects_gate_criterion_update` (text / needs-evidence; scope is fixed), `projects_gate_criterion_delete` (its acks go too). - **Comments & checklists** — `projects_card_comments`, `projects_card_findings` (the card's findings — not in the comments list; read them before working a handed-over card), `projects_card_comment`, `projects_comment_update` (author-only edit), `projects_card_checklist`, `projects_checklist_add` (text, or `ref_card_id` to track another card), `projects_checklist_update` (tick, rewrite, reorder via `position`; card-tracking items refuse text/done), `projects_checklist_delete`. - **Labels & priorities** — `projects_labels`, `projects_label_create`, `projects_label_update`, `projects_label_delete` (detaches board-wide), `projects_card_label`, `projects_card_unlabel`; `projects_priorities` (most urgent first; `position` is the 0-based rung), `projects_priority_create` (appends at the bottom), `projects_priority_update` (re-rungs via `position`), `projects_priority_delete` (cards fall back to no priority). - **Attachments** — `projects_card_attachments`, `projects_comment_attachments`, `projects_attachment` (read one paged: UTF-8 inline, binary as base64; `offset`/`max_bytes` walk files up to the 10 MB cap), `projects_attachment_upload` (base64 bytes to a card or a comment; virus-scanned, names unique per card/comment). - `repos_list`, `repos_overview`, `repos_tree`, `repos_file`, `repos_commits`, `repos_commit` — read-only git browsing (hosted repositories and mirrored connector repos serve content; un-mirrored external ones answer metadata + tracked activity). - **Chat** — `chat_channels` (your channels and DMs; also advertises the server's feature set), `chat_users`, `chat_search` (channels, message text and people across everything you can see), `chat_messages` (a channel's top-level messages, paged), `chat_thread`, `chat_send` (channel or thread; `idempotency_key` guards retries), `chat_edit` (own messages), `chat_delete` (own always; anyone's with channel owner/admin moderation), `chat_dm` (open or find a DM), `chat_attachment` (read one paged, same shape as `projects_attachment`). - **Alerts** — `chat_alert` (post + push an alert; `severity: "urgent"` bypasses the presence grace period; reports `delivered_to` and `suppressed`), `chat_alerts` (a channel's recent alerts, deduped ones included). - **Hats** — `projects_hats` (a board's hats: name, role — implement / review / explore — and the instructions their wearer gets). - **Agent channels** — `chat_fleet` (every agent channel you're in with live bridge status, unread count, newest alert and the cards it holds), `chat_parked` (the steering queue: messages parked until the agent's turn ends), `chat_parked_cancel` (drop one of your own before it lands). ## Prompts One prompt, **`work-card`** (card #385): it sets a session up to work a card the way ogma's own agents do — claim it, read its `guide`, wear its hat, do the open instructions first, talk in the card's room, ask the lead rather than guess, keep the Story current, then move it on and release it. Arguments: `card_id` (the card), or `project_id` alone to take the next ready card from that board. In Claude Code it is `/mcp__ogma__work-card`. `chat_send` takes `kind: "question"` (a bot asking the people on a card — **Needs you** on the card, the lead rung), and in a card's room `intent` (`note` / `instruction` / `answer`) with `answers_id`. ## Skills (SEP-2640) The tools above say what each call does; the skills say how to work here. Instructions are capped in size and tool descriptions cannot carry a workflow, so the guidance travels as skills instead — two of them, because the server cannot tell its readers apart and the rules differ: - **`ogma`** — for anyone: a person's own session as much as an agent. File a card so it can actually be scheduled, show work as it happens, build an epic out of children, why a `/c/` link means a card in a board body and a channel in chat. A person's session needs nothing else. - **`ogma-fleet`** — for a bot account working a board's queue, on top of `ogma`: claiming and the WIP limit, parking work that is waiting, work phases versus attention, handing a card back, reporting to watchers, and what counts as an approval arriving over chat. These are the rules the server refuses a person's cards anyway, which is why they are split out. - **Extension**: `io.modelcontextprotocol/skills`, declared in `initialize` with `directoryRead: true`. It commits this server to `skills/list` and `skills/get`, and additionally offers `resources/directory/read`. - **Methods**: - `skills/list` — every skill served, each entry carrying its `SKILL.md` frontmatter verbatim and a `{uri, digest, size}` row per file. The catalogue is small and fixed, so there is no `nextCursor`. - `skills/get` `{uri}` — one entry, identical in shape to a listing entry. A URI this server does not serve answers `-32602`, the code `resources/read` uses for an unknown resource. - `resources/directory/read` `{uri}` — the direct children of a directory resource (`skill://ogma`), files and subdirectories, the latter marked `inode/directory`. - `resources/list` / `resources/read` — the skill's files as ordinary MCP resources. Reading a `SKILL.md` returns bytes; it does not activate the skill, which is the host's own decision. - **URIs**: `skill:///`; the last path segment is the skill's `name`. The workspace serves `skill://ogma/SKILL.md`, `skill://ogma-fleet/SKILL.md` and `skill://ogma-acceptance/SKILL.md`. With agents on it also serves `skill://ogma-acceptance-live/SKILL.md`, the live pass over a whole acceptance column. - **Integrity**: each entry carries a `sha256:` digest and byte `size` per file. A host verifies what it reads against the entry it approved; the digests are unsigned and come from this same server, so they prove consistency, not trustworthiness. - **Plain HTTP**: the same bytes, public and unauthenticated, at `/skills/{path}` — the resource URI with `skill://` struck off. So `skill://ogma/SKILL.md` is also `GET /skills/ogma/SKILL.md`, the fleet skill `GET /skills/ogma-fleet/SKILL.md`, and the acceptance skill `GET /skills/ogma-acceptance/SKILL.md`. Fetch them that way in a client that speaks no skills extension, or read them before connecting at all. ## Everything else - `/` — the tabbed workspace shell for a signed-in session; a signed-out visitor gets the public landing page instead of a login bounce (also at `/start`, a stable link). Its **Home** tab has a tab per board you belong to, after a pinned **All**, sorted by recent activity, by most activity this week, or A–Z (boards that don't fit fold into **More ▾**, in the same order). Each says, in order: **Needs you** (open questions and plan approvals from pool workers on cards you lead or watch), **Mentions** (on cards, and in chat — a card's room counts as its board's; DMs are on All), and **Cards due** (your open cards by due date, then priority; undated last). It refreshes every 30 s. - `/profile` — display name, theme, **API tokens** (mint/revoke, scoped). - `/admin` — consolidated platform administration (platform admins; each topic is gated on its owning app's `:admin` scope): Users, API Tokens, Projects, Invitations, Channels. With agents on, also Agents, Base images, Prompts, Workspace docs (the shared documents agents are given, with a review queue for the changes agents propose — each proposal shows its diff and is accepted or rejected at `/admin/docs/proposals/{id}`), and Workspace limits (per-person quotas; blank restores the deployment default). - `GET /api/healthz`, `GET /api/readyz` — liveness/readiness. - `GET /metrics` — Prometheus text (block from the public internet). - The apps themselves document their own HTTP APIs at their hosts' `/llms.txt` (projects, chat, repos).