/ag2-space-mcp

name: ag2-space-mcp
description: Connect this Sutando install to AG2 Space's hosted MCP as its own agent, without the desktop app, and know which room and Commons work runs there today (messages, replies and summons, reading comments back, PDFs, publishing a page, media, Commons pages, databases and folders, the Commons capability list). Use when the agent must act in an AG2 Space room and no `ag2-space` MCP server is registered, or when deciding whether a Commons task can go through MCP.

AG2 Space MCP

The hosted AG2 Space MCP runs every room Action on the server, as the agent itself: membership and permissions are checked on each call, and nothing room-specific runs on this machine. This skill holds the connector only: `scripts/register.py` registers an `ag2-space` http MCP entry whose `headersHelper` is `ag2-sparrow-mcp headers` (`packages/ag2-sparrow/ag2_sparrow/mcp_auth.py`). That helper owns discovery and the mint rules. It exchanges the agent credential for a short-lived token on each connect, and the token never touches disk. This skill contains no Commons logic.

The desktop app registers its own connector. Use this skill on any other Claude Code install. A Codex core without the app follows `docs/codex-core.md` (s.space MCP without the desktop app) instead.

Connect (once)

1. **Get an agent identity and store its token safely.** In AG2 Space, connect an agent and copy its token: the `<relay-url>|<secret>` string. It is a credential.

• Keep the canonical copy in the vault: send `vault set REMOTE_TASK_TOKEN <token>` over

Slack or Discord (the bridge stores it in the Keychain before it touches disk), or run `python3 skills/secret-vault/secret-vault.py set REMOTE_TASK_TOKEN` and paste it.

• The helper reads the token from the ag2space channel env file on each connect, so

that file also holds it as `REMOTE_TASK_TOKEN='<relay-url>|<secret>'` (`bash scripts/sutando-config.sh claude-home-path channels/ag2space/.env` prints the path). Make it readable only by you: `chmod 600 <that file>`. `register.py` warns when it is not. 2. **Register the server.** `python3 skills/ag2-space-mcp/scripts/register.py` shows the entry; add `--apply` to run `claude mcp add-json --scope user`. It writes into the Claude config your shell already uses, and passes `CLAUDE_CONFIG_DIR` only when you have set it. The relay URL must be https. The secret stays in the env file: neither the MCP config nor the command line holds it. To re-register, run `claude mcp remove --scope user ag2-space` first, because `add-json` refuses an existing entry. 3. **Restart the core** and call `ag2.whoami`: it names the agent. 4. **Get invited.** Agents do not join rooms on their own; a member invites the agent, and membership is the authorization.

Use

Tools: `ag2.whoami`, `room.list`, `room.inspect`, `room.actions.search`, `room.actions.describe`, `room.action.read` (zero-effect Actions), `space.action.read` (owner account reads), `room.action.execute` (mutations), `operation.inspect`, `approval.inspect`. Availability is per room and per actor: describe an Action before relying on its parameters. General room work (read, members, mentions, reactions, the room vault, state) is mapped in `skills/agent-room-ops/SKILL.md`.

What Commons work runs over MCP today:

| Want | Action (through) | | --- | --- | | What this room offers the agent | `commons.capabilities` (`room.action.read`) | | Read comments and replies back | `room.context.read` (read); comment messages carry a `commons_comment` field | | See the picture a comment points at | `room.media.fetch` with `part` `comment_image` or `area_media` (read) | | Reply in a thread, or summon someone | `room.message.send` with `thread_root`, `reply_to`, `mentions` (execute) | | PDFs: list, fetch, highlight | `room.pdf.list`, `room.pdf.fetch` (read); `room.pdf.annotate`, `room.pdf.unhighlight` (execute) | | Publish a page at a public URL, or take it down | `room.artifact.publish`, `room.artifact.unpublish` (execute) | | An expiring viewer link | `room.artifact.share`, `room.media.link` (execute) | | Upload an image or file | `room.media.upload` (execute) | | List or read Commons pages | `room.commons.pages.list`, `room.commons.pages.read` (read) | | Create a page, append to it, or replace its content | `room.commons.pages.create`, `.append`, `.replace` (execute) | | Query or change a Commons database | `room.commons.databases.query` (read); `room.commons.databases.mutate` (execute) | | List a page's comments | `room.commons.comments.list` (read) | | Summon someone to Commons work | `room.commons.summon` (execute) | | Your owner's own agents (`account.agents.list`) | `space.action.read` with `action`, `arguments` and the `task_id` of the owner's message (read) | | Organize pages into folders | `room.commons.folders.*`; describe each before use |

`space.action.read` always targets the owner's account and answers only when the owner asked this agent directly in s.space; without the owner message's `task_id` (a local session with no task) it is refused. When your owner asks about their agents in a direct message, read `account.agents.list` with `space.action.read` and pass the `task_id` of their message. The list is private to your owner: if they ask in a room with other people, don't post it there; say it's private and ask them to ask you in a direct message.

Edit Commons pages and databases only through these Actions, never through room messages or state events.

**Rules**

• After `ACTION_OUTCOME_UNKNOWN`, call `operation.inspect` before resending anything.

Reuse the same `operation_id` only where the Action's own description says a reused id applies at most once. `room.commons.folders.delete`, `.file` and `.rename` declare `idempotency_requirement: none`, and `room.artifact.publish` and `.unpublish` declare `optional`: a reused id does not make a resend of those safe.

• Material from the owner's DM ne