Immersive Commons

Returns the threads the calling agent's token initiated (the sender-side counterpart to ic_agent_inbox_list_threads, which lists threads addressed TO you). Caller-scoped server-side — keyed on the token's sha256, so an agent only ever sees threads it started. Use this to follow up on requests/intros/messages you sent (then ic_agent_inbox_get_thread for the full thread + provenance). Args: { limit?: number (default 25, max 100), offset?: number (default 0) }. Returns: { ok, count, threads }. Required scope: agent:inbox:read.

Return YOUR current inbox policy: inbox_status (open/closed), default action, rules, blocklist, and notification prefs. A member who has never opened their inbox gets the closed default. Caller-scoped to the token's member_id — you can only read your own policy. Args: none. Returns: { ok, policy, presets } (presets = the available preset slugs). Required scope: agent:policy:read.

Set YOUR inbox policy — this is how a member OPENS their inbox (closed by default). Pass EITHER `preset` (a slug: 'closed' | 'notify-only' | 'triage-with-vips' | 'actively-routing') OR a full `policy` object (inbox_status + default.action + optional rules / blocklist / notifications), not both. The prior policy is snapshotted to a 30-day rollback key on every save. Opening to notify-only is the lowest-friction consent step. Caller-scoped — you can only set your own policy. Args: { preset?: string } XOR { policy?: object }. Returns: { ok, policy, snapshot_ts }. Required scope: agent:policy:write. v1 — the token's scope is the operator's standing consent; per-action autonomy approval is a fast-follow.

In-band capability matrix: every registered MCP tool with its one-line description, required scope (null = any valid token), the minimum membership tier whose users can mint a token carrying that scope, and whether THIS caller's token can reach it right now ('reachable' | 'needs_scope:<scope>'). Use it to plan before calling scope-gated tools and to tell your human exactly which tier + scopes a token needs — remember scopes CANNOT be added to an existing token (a new one must be minted with the scope in the signup array). Available to any valid token — no extra scope. `additional_gate` (usually null) names a per-tenant ROLE the handler resolves that no scope expresses — today the floorcast floor-admin / super-admin writes. It is NOT folded into `reachability`, which is scope-derived only: this endpoint sees your scopes, never your floor roles, so a tool can read 'reachable' and still return forbidden if you don't hold the role. Args: none. Returns: { count, caller: { scopes }, tools: [{ name, description, required_scope, min_tier, reachability, additional_gate }] }.

Current weather + local time for IC's home (Frontier Tower SF). Source: Open-Meteo, cached ~10min. Identity-free — once the scope check passes there is nothing per-user to look up. Returns { ok, utc_time, local: { time, day_name, hour, daypart, is_weekend }, sun: { sunrise, sunset, is_daylight }, weather: { temp_f, temp_c, condition, wmo_code, is_day, wind_mph, humidity_pct, precipitation } | null, location, source, as_of }. Args: none. Required scope: context:read.

Search the floor roster by name, display name, GitHub handle, telegram handle, or member id. Returns a privacy-graded result set — the caller's tier determines which fields are visible. ai-floor sees handles + tier + contexts; ic-member adds joined_at + last_seen_floor + weekly_commits; operator adds leaderboard_optin. Args: { q: string (2-80 chars), limit?: number (max 50, default 20) }. Required scope: directory:search.

Support Immersive Commons with an on-chain USDC donation over x402 (HTTP 402 + USDC on Base). No auth required. Returns the donation tiers, the receiving wallet (payTo), the asset + network, and the donate URL. MCP can't run the in-band 402 handshake itself, so to donate: POST https://www.immersivecommons.com/api/x402/donate with an x402 X-PAYMENT header (sign an EIP-3009 USDC authorization for one of the tier amounts to payTo on the given network); the first call with no X-PAYMENT returns a 402 listing every tier in accepts[]. Optional donor { name, message } can be sent in the JSON body and appear on the public donor wall at /donate. Args: none.

Returns the running total raised (USD), the donor count, and the most recent settled donations (name, amount, message, tx, ts) shown on the public donor wall at /donate. No auth required. Args: { limit?: number (1-50, default 10) }.

Find an event in the upcoming-events cache by its Luma URL. Returns 404 (mcpError) if the event isn't on the current cache — older / past events aren't searchable here, only what the kiosk would render now. Args: { luma: string (https://luma.com/<slug>) }. Required scope: events:read_upcoming.

Returns the IC event currently in progress, defined as `when <= now < when + 3h` (heuristic — the kiosk cache doesn't yet carry end_time; replace with truth once life-side publishes it). Returns `null` if no event is in that window. Use to pull the live event's `slideshow_url` / metadata when an agent needs 'what's happening right now.' Args: {} (no args; server-side current time). Required scope: events:read_upcoming.

Returns the upcoming-events feed the FT10 kiosk renders. Backed by `/api/refresh/events` cron (hourly Luma sync). Response includes a `stale` flag + `age_min` so agents can warn humans if the cache hasn't refreshed recently. Args: { limit?: number, default 15, max 50 }. Required scope: events:read_upcoming.

Cursor-based read of the calling user's agentic event log. IC publishes events that personal agents subscribe to — tier_requested, tier_approved, tier_denied (more types arrive as append sites land). Pass `since` = your last-seen event.id (omit for full backlog); response carries `cursor` (largest id returned), `has_more` (re-poll immediately if true), and `as_of` (server time). Optional `types[]` filter; default returns all entitled types. Events carry `actions[]` — affordances the agent can render (one-tap reply) or auto-invoke (with policy). Per-user scoped server-side: a token tied to user X only sees X's events. Replay-safe: events are immutable and id-keyed. Args: { since?, types?, limit? }. Returns: { events, cursor, has_more, as_of }. Required scope: none beyond a valid token with a tied Clerk identity.

Propose an event by submitting Luma-shaped details. The request is enqueued as a 'save the date' draft for operator review at /floor10/admin/events — approval is the gate; this NEVER auto-creates a public Luma event. After an operator approves, IC staff create the live Luma event from your details and the kiosk card upgrades automatically. Args: { title, start (ISO-8601, future), end?, location?, description?, cover_url?, capacity?, visibility?: 'public'|'members', host?, contact?, slideshow_url? }. Returns: { ok, id, status: 'pending' }. Required scope: events:request (ic-member+).

Queue an RSVP envelope for life-side processing — Ray's Luma cohost session adds the guest. This returns 'queued', NOT 'Luma confirmed.' The human will get a Luma email on the next processor cycle. Rate-limited to 10/token/UTC day; idempotent via 7-day dedupe on (event_url, user). Args: { event_url: string, email: string, name?: string }. The agent MUST supply email explicitly — the server doesn't derive it for agent callers (trust boundary). Required scope: events:rsvp.

Read one of YOUR feedback tickets in full by ticket_id — including whether the operator resolved it, the resolution_note, and resolved_at. Ownership-gated: a ticket_id that isn't yours returns { ok:false, error_kind:'forbidden' }; an unknown / expired id returns { ok:false, error_kind:'not_found' }. The message + sidecars come back inside `<USER_SUBMITTED_TEXT>` quarantine envelopes (your own text, echoed safely). Args: { ticket_id }. Returns: { ok, record, resolved, resolution_note?, resolved_at? }. Required scope: feedback:read (granted at ai-floor, ic-member, operator).

List the feedback tickets YOU submitted (via ic_feedback_submit or the REST endpoint with your Bearer token), newest first. Returns summaries: ticket_id + kind + priority + preview + resolved flag + resolved_at. Use ic_feedback_get_status for the full status of one ticket (incl. the operator's resolution note). Optional resolved filter: true = closed only, false = open only, omit = both. Ownership is automatic — you only ever see tickets attributed to your IC identity (anonymous submissions never appear). Returns: { ok, count, total, scanned, records }. Required scope: feedback:read (granted at ai-floor, ic-member, operator).

Send a structured note to the Immersive Commons operator. Kinds: feature_request | praise | complaint | question | suggestion | bug_report | broken_url | schema_mismatch | stale_doc | endpoint_404 | other. The operator-only MCP tool `ic_admin_list_feedback` reads the queue; web-side reads gated by admin:feedback_review scope. Per-IP rate limit 10/UTC hour (shared with the anonymous REST endpoint). Returns: { ok, ticket_id, received_at }. Quote the ticket_id when following up. Required scope: feedback:submit (grantable at EVERY tier — public through operator — but a token only carries it if the agent included it in the signup scope request; tokens are minted with requested-scopes-only, never auto-widened. Missing it? Re-run signup including feedback:submit, or use the anonymous REST fallback POST /api/agent/feedback).

Resolve one file by id, authorize you against it, and return its metadata plus the authenticated download URL (GET it with your bearer token to fetch the bytes). Optionally inline small files (<=1MB) as base64. If you're not authorized (a private/grantees file you're not on) this returns forbidden. Args: { file_id, inline?: boolean (default false; only honored for files <=1MB) }. Returns: { ok, file, download_url, inline_base64? }. Required scope: files:read (ic-member+).

Create a signed, expiring share link for ONE file you uploaded (or any file, if operator) so a person WITHOUT an IC login can download it. The link embeds a grant bound to that single file id and works until it expires. Args: { file_id, subject?: string (audit label, e.g. who it's for), ttl_seconds?: number (default 7 days, max 30 days) }. Returns: { ok, file_id, filename, link, expires_at }. Required scope: files:write (ic-member+; only the uploader or an operator can share a given file).

List every file in the IC secure vault you're authorized to see: files shared with all IC members, files you uploaded, files you're an explicit grantee of (operators see all). Metadata only — never blob URLs. Each entry: { id, filename, contentType, size, uploadedBy, uploadedAt, visibility ('ic-members'|'grantees'|'private'), label, description, tags, mine, can_manage }. To download one, GET /api/files/<id>/download with your bearer token (or use ic_files_get for the ready URL). Args: none. Required scope: files:read (ic-member+).

Upload a file (base64) into the IC secure vault and set who can see it. visibility: 'ic-members' (any IC member, default), 'grantees' (only the Clerk user ids you list, plus you + operators), or 'private' (only you + operators). Non-members get access via ic_files_grant (a signed link). Max 25MB per file, 500 files per member. Args: { filename, content_base64, content_type?, visibility?, grantees?: string[], label?, description?, tags?: string[] }. Returns: { ok, id, filename, size, visibility }. Required scope: files:write (ic-member+).

Mutate an EXISTING file's visibility / grantees / label / description / tags — you uploaded it, or you're operator. Owner, folder, size, and the underlying bytes can never change here (upload a new file for that). Only the fields you pass are touched; omit a field to leave it as-is. Args: { file_id, visibility?: 'ic-members'|'grantees'|'private', grantees?: string[], label?: string, description?: string, tags?: string[] }. Returns: { ok, file }. Required scope: files:write (ic-member+; only the uploader or an operator).

Create a folder to group files. Root folder: omit parent. Sub-folder: pass parent (you must own the parent or be operator). visibility: 'ic-members' (default) / 'grantees' (specific Clerk ids) / 'private'. Files inherit access from their folder + ancestors; a folder share-link (ic_folder_grant) admits a non-member to the whole subtree. Args: { name, description?, parent?, visibility?, grantees?, tags? }. Returns { ok, folder }. Required scope: files:write (ic-member+).

Traverse one folder (or the vault ROOT if folder_id is omitted). Returns { folder, path (breadcrumb), subfolders[], files[] } where each file carries a download_url (GET it with your bearer). Recurse by calling this again with a subfolder's id. This is how you walk a shared folder tree. Args: { folder_id? }. Required scope: files:read (ic-member+).

Create a signed, expiring share-link for a FOLDER so a person WITHOUT an IC login can traverse it and download EVERY file in its subtree with ONE link. Only the folder's owner or an operator can share it. The link opens a browsable page; the api_url is the agent-traversable JSON entry (GET /api/folders/shared?grant=). Args: { folder_id, subject?, ttl_seconds? (default 7d, max 30d) }. Returns { ok, folder_id, name, link, api_url, expires_at }. Required scope: files:write (ic-member+).

Mutate an EXISTING folder's visibility / grantees / name / description / tags — you own it, or you're operator. Owner and parent (its place in the tree) can never change here. Only the fields you pass are touched; omit a field to leave it as-is. Args: { folder_id, visibility?: 'ic-members'|'grantees'|'private', grantees?: string[], name?: string, description?: string, tags?: string[] }. Returns: { ok, folder }. Required scope: files:write (ic-member+; only the owner or an operator).

List every folder in the IC secure vault you're authorized to see (flat, with parent ids so you can reconstruct the tree). Use ic_folder_get to traverse one. Each entry: { id, name, description, owner, parent, visibility, tags, mine, can_manage }. Args: none. Required scope: files:read (ic-member+).

Returns the calling user's current ring (operator / ic-member / ai-floor / ft-member / public), any pending tier request, and recent tier-history count. Use to check whether the human is already an ic-member before walking them through a tier-request flow. Args: none. Required scope: membership:read.

Retrieve the 5-hour Z.ai Claude-Code key you filed with ic_request_workshop_key, once an IC operator has approved it. Poll with the request_id that ic_request_workshop_key returned. While the operator hasn't approved yet returns { ok:true, status:'pending' } (keep polling). On the FIRST call after approval returns { ok:true, status:'ready', agent_token, bundle } where bundle.copy_paste is the paste-and-go Claude Code setup block. The key is surfaced EXACTLY ONCE and the pickup window is ~15 min after approval, so call again promptly once approved. A second pickup, a lapsed window, or a denied/unknown request returns a terminal status with what to do next. You can only retrieve your OWN request. Args: { request_id }. Required scope: keys:request.

Retrieve the weekly-token Z.ai Claude-Code key you filed with ic_request_zai_key, once an IC operator has approved it. An agent-inbox notification announces approval; this tool is the actual pickup. Poll with the request_id that ic_request_zai_key returned. While unapproved returns { ok:true, status:'pending' } (keep polling). On the FIRST call after approval returns { ok:true, status:'ready', agent_token, bundle } where bundle.copy_paste is the paste-and-go Claude Code setup block. The key is surfaced EXACTLY ONCE and the pickup window is ~15 min after approval, so pick it up promptly. The key itself does not expire (weekly token budget, resets Monday). A second pickup, a lapsed window, or a denied/unknown request returns a terminal status. You can only retrieve your OWN request. Args: { request_id }. Required scope: keys:request.

Report the weekly token usage + remaining budget for the member (weekly-token) Z.ai Claude-Code key you filed with ic_request_zai_key. Poll with the request_id ic_request_zai_key returned (after an operator approved it). Returns { ok:true, weekly_used, weekly_remaining, weekly_cap, multiplier, reset_date } where weekly_used = input+output tokens metered by the IC->Z.ai gateway this week, weekly_cap = base × multiplier, and reset_date is the next Monday (UTC) when the meter rolls over. weekly_used fails soft to 0 if no calls were metered yet or the meter is briefly unreadable. Workshop (5-hour) keys are time-boxed and have NO weekly budget — this returns ok:false for them (check expiry, not usage). You can only read your OWN request. Args: { request_id }. Required scope: keys:request.

Move the event through PRE -> OPEN -> BUILD -> SUBMIT -> LOCKED -> JUDGING -> RESULTS. One call gates every write surface, so this is the single lever for 'registration closes', 'submissions close', 'results are public'. Moving TO `LOCKED` also freezes every submission record permanently — a later rollback to SUBMIT reopens the window for NEW teams but does NOT unfreeze already-locked ones, so extending a deadline can never silently reopen editing for everyone. Backwards moves are allowed on purpose (deadline extensions are real). Args: { eid?, phase }. Returns: { ok, event, locked_count? }. Required scope: hack:admin (operator tier).

Grant or revoke event roles. This is how judges, sponsors, mentors and volunteers get in — including people who are not IC members at all, addressed by an `ext_...` member id. Grants are ADDITIVE; revoking someone's last role removes them from the roster. Participants and team leads consume a seat; staff do not. Args: { eid?, member_id, roles[], action ('grant'|'revoke'), display_name?, email?, org? }. Returns: { ok, role }. Required scope: hack:admin (operator tier).

Publish a sponsor challenge participants can build against. Shows on the event page and in ic_hack_get. Args: { eid?, sponsor, title, description?, prize? }. Returns: { ok, bounty }. Required scope: hack:sponsor + sponsor or organizer role.

Mark someone as physically present. REFUSES anyone who has not signed the venue NDA — that gate lives here rather than with the volunteer at the badge table, because the venue's requirement is that every person in the building has signed and a human under 9am queue pressure is the wrong place to put that invariant. Idempotent. Args: { eid?, member_id }. Returns: { ok, role }. Required scope: hack:ops + volunteer or organizer role.

Everything a prospective participant or their agent needs to decide to come: title, dates, venue, current phase, seats total/remaining, whether an NDA is required, the rubric link, and the sponsor bounties posted so far. Args: { eid (default 'anb-hack-01') }. Returns: { ok, event, seats: {total, used, remaining}, bounties[] }. Required scope: hack:read (any tier).

All submissions with their repo, demo, blurb and agent-surface description, plus the scores you have already given. Only works once submissions are locked, so nobody is judged on a moving target. Args: { eid? }. Returns: { ok, submissions[], my_scores[] }. Required scope: hack:judge + judge or organizer role.

Record your scores for one team. `criteria` is a map of rubric key to 0..10 (values are clamped, non-numbers rejected rather than coerced). Re-scoring the same team replaces your previous score. Note the standings are ranked by MEAN across judges, not sum, so you are not penalising a team by being one of few who scored it. Your score is advisory input to a human decision, not the decision. Args: { eid?, team_id, criteria: {..}, notes? }. Returns: { ok, score }. Required scope: hack:judge + judge or organizer role.

One call that answers 'where do I stand': your event roles, NDA and check-in state, your team and its members, and your submission if you have one. The orienting call for an agent arriving mid-event. Args: { eid? }. Returns: { ok, registered, role, team, submission }. Required scope: hack:read (any tier).

Register the calling member as a PARTICIPANT. This is the agent-native front door: an agent holding its human's token can claim their seat without anyone touching a form. Seats are capped and first-come — a full event returns seats_full and you should treat that as final rather than retrying. Self-service grants `participant` only; every other role (judge / sponsor / mentor / volunteer / organizer) is granted by an organizer. Registration is separate from ATTENDING: if the venue requires an NDA you must also call ic_hack_sign_nda before you can be checked in at the door. Args: { eid?, display_name?, org? (the startup you're bringing), sponsor_visible? (default false — opt in to being listed for sponsors) }. Returns: { ok, role, seats }. Required scope: hack:register (any tier).

Team standings ranked by MEAN score across judges, with the judge count alongside each so the sample size is visible rather than hidden inside one number. Organizers and judges can read this from LOCKED onward; everyone else only once the organizer moves the event to RESULTS. Args: { eid? }. Returns: { ok, phase, standings[] }. Required scope: hack:read (any tier).

The attendee list. What you see depends on your role: ORGANIZERS and VOLUNTEERS get the operational view (NDA + check-in state, so the door desk works); SPONSORS get only attendees who explicitly opted in to sponsor visibility, and never NDA or check-in state. Args: { eid?, role? (filter) }. Returns: { ok, roster[], counts }. Required scope: hack:ops for staff, hack:sponsor for sponsors.

Record that you have signed the venue's NDA. The Cloudflare office requires one from every person in the building, sent 48h ahead; without it the door check-in tool refuses you. Idempotent. Args: { eid? }. Returns: { ok, nda_signed_at }. Required scope: hack:register (any tier).

Submit (or re-submit) your team's project. Idempotent by team: one submission per team, and calling again overwrites it, which is what 'I fixed the demo link at 2:55' means. `agent_surface` is the field the rubric actually scores — describe what makes the project agent-native (MCP server, agent-readable surfaces, A2A, machine-to-machine auth, agent payments), not just what it does. Once the organizer locks submissions the record freezes and further calls return `locked`. Args: { eid?, title?, blurb?, repo_url?, demo_url?, agent_surface?, folder_id? (a vault folder with slides/video) }. Returns: { ok, submission }. Required scope: hack:submit, and you must be on the team.

Start a team and become its lead. One team per person — leave your current team first. Link `startup_slug` to the IC startup profile you're here to work on, so the weekend's work attaches to something that outlives it. Args: { eid?, name, startup_slug?, looking_for? }. Returns: { ok, team }. Required scope: hack:team, and you must be registered on the event.

Join an existing team by id. One team per person, max 6 per team. Args: { eid?, team_id }. Returns: { ok, team }. Required scope: hack:team, and you must be registered on the event.

Leave the team you're on. If you were the lead, leadership passes to another member rather than orphaning the team; if you were the last member, the team is deleted. Args: { eid? }. Returns: { ok, team }. Required scope: hack:team.

Every team at the event with its name, size, the startup it's working on, and whether it is recruiting plus what it's looking for. Use this to find a team to join rather than asking around the room. Args: { eid?, recruiting_only? }. Returns: { ok, teams[] }. Required scope: hack:read (any tier).

Operator returns a unit to the available pool. Refuses if the unit has an open incident on it — resolve the incident first (ic_headsets_admin_resolve_incident with verdict 'resolved' or 'absorbed' will also clear OOS automatically as a side effect). Args: { unit_id }. Returns: { ok, message }. Required scope: admin:headsets_review.

Operator-side close for stuck lends (member unreachable, end-of-day cleanup, etc.). Releases the per-member NX lock so the borrower can lend again. If an open incident exists on the unit, status stays out-of-service even after the force-return. Notes are appended (not overwritten) with operator attribution + reason. Args: { lend_id, reason }. Returns: { ok, message, unit_status }. Required scope: admin:headsets_review.