On My Radar
On this page

Guides Agents and MCP

MCP tools for topics, sharing and publishing

Reference for the fifteen MCP tools that organise radars into topics, share radars and topics with existing users, remove access, and publish radars.

Updated October 30, 2026 · Checked against On My Radar build 2c4905d

These fifteen tools group radars into topics, share radars with people who already have an account, take access away, and publish a radar. The rule behind all of them: an agent may organise, but may never widen access beyond what you could do yourself. Ids and scopes are explained in the MCP reference overview.

What an agent cannot do here

Some acts are refused at any scope, because they are a person's decision on a real screen.

  • Turn a topic's cascade on or off. There is no tool for it.
  • Share a topic that cascades.
  • File a radar into a cascading topic that other people are already in.
  • Grant owner on a radar, demote or remove a co-owner, or withdraw an invitation to co-own.
  • Share or invite an address that has no On My Radar account.
  • Share the drop box, publish it, or give it a webhook.

Each refusal names what to ask the person to do instead. See Sharing and roles and Invites.

Topics

A topic is a container for radars. Sharing a topic does not share the radars in it unless the topic is set to cascade, which only the person can do, in the app.

list_topics

Lists every topic you can reach.

  • Scope: radars:read. Read-only.
  • Optional: includeArchived (boolean, default false).
  • Returns: for each topic, id, name, tagline, radarCount, memberCount, cascade and your role. radarCount is how many radars in it you can read, not how many it holds.

read_topic

Returns a topic and the radars in it that you can already read. Radars in the topic you have not been given are not listed, and neither are archived radars.

  • Scope: radars:read. Read-only.
  • Required: topicId (string).
  • Returns: topic (with cascade), a note explaining what cascade means for this topic, and radars.

create_topic

Creates a topic. A new topic has no members and does not cascade, so creating one grants nobody anything.

  • Scope: radars:write. Writes.
  • Required: name (1 to 120 characters).
  • Optional: tagline (up to 300), description (up to 2,000), accent, glyph (values listed in the tool's schema).
  • Returns: id, name, cascade and url.

update_topic

Renames a topic, changes its tagline, description, colour or glyph, or archives it. It never changes the cascade switch.

  • Scope: radars:manage, and you must own the topic. Writes.
  • Required: topicId (UUID), plus at least one field.
  • Optional: name, tagline, description, accent, glyph, archived (boolean), position (integer 0 to 9,999).
  • Returns: id, name, archived.

delete_topic

Deletes a topic you own. Its radars survive and become ungrouped. Access that reached a radar only through a cascading topic is removed.

  • Scope: radars:manage. Writes, and cannot be undone.
  • Required: topicId (UUID).
  • Returns: how many radars were freed (radarsFreed).

set_radar_topic

Files a radar into a topic, or takes it out with topicId: null. Filing never touches the radar's own member list.

  • Scope: radars:manage. Writes. Filing in needs manage access on both the radar and the topic. Taking a radar out (topicId: null) needs manage access on the radar only.
  • Required: radarId (string), topicId (string, or null to remove the radar from every topic).

Refused when the topic cascades and already has other members, because that would hand those people the radar. A cascading topic with no other members is fine to file into. A topic holds at most 200 radars. The drop box and smart radars can never be in a topic.

{ "radarId": "5b2c7e2e-1f0a-4a55-9a53-0d1f6f3b8a10", "topicId": null }

share_topic

Gives someone who already has an account a grant on a topic, by email. On a topic that does not cascade, the grant conveys the grouping and no radar access.

  • Scope: radars:manage. Writes.
  • Required: topicId (string), email (a valid email address).
  • Optional: role: viewer (default) or editor. It only matters if the topic is later set to cascade.
  • Returns: the grant, with a note that radars are shared separately with share_radar.

Refused on a cascading topic, and refused if the address has no account.

list_topic_members

Lists who holds a grant on a topic, including invitations not yet accepted.

  • Scope: radars:read. Read-only.
  • Required: topicId (string).

remove_topic_member

Removes one topic grant, including access derived from its cascade. Independent grants on individual radars survive. The owner cannot be removed.

  • Scope: radars:manage. Writes. Idempotent.
  • Required: topicId (UUID), userId (UUID).
  • Returns: { "removed": "<userId>" }.

revoke_topic_invite

Cancels one unaccepted topic invitation without removing accepted members.

  • Scope: radars:manage. Writes. Idempotent.
  • Required: topicId (UUID), email (a valid email address).
  • Returns: { "revoked": true }.

Sharing and publishing radars

share_radar

Gives someone who already has an On My Radar account access to a radar, by email. It is refused if that address has no account, because inviting a new person is something the user has to do from the app. Call list_radar_members first if you are not sure which case you are in.

  • Scope: radars:manage, and you must be the owner. Writes.
  • Required: radarId (string), email (a valid email address).
  • Optional: role: viewer (default) can read, editor can add and change blips. owner is in the schema but is refused on a connection.

A person who is newly added is told by email and in the app. Changing the role of someone who already has access sends nothing. The drop box cannot be shared by an agent.

{ "radarId": "5b2c7e2e-1f0a-4a55-9a53-0d1f6f3b8a10", "email": "[email protected]", "role": "editor" }

list_radar_members

Lists who can see a radar, including invitations not yet accepted, and which agents can be addressed on it. Agents appear under agents, not members, because an agent holds no grant of its own. It reaches exactly what its owner reaches.

  • Scope: radars:read. Read-only.
  • Required: radarId (string).
  • Returns: members (people reached directly or through a cascading topic, marked via: "topic") and agents, each with name, mention (@handle), handles (qualified forms, used when two people have an agent with the same handle) and actsFor.

If you can read a published radar only through its public link, with no share or ownership of your own, the member list is refused. A public link is a way to read a radar, never a way to list the people around it.

remove_radar_member

Removes one direct radar grant. Access the person has through a topic survives. The owner cannot be removed.

  • Scope: radars:manage. Writes. Idempotent.
  • Required: radarId (UUID), userId (UUID).
  • Returns: { "removed": "<userId>" }.

Removing a co-owner is refused for an agent.

revoke_radar_invite

Cancels one unaccepted radar invitation. It does not revoke an accepted membership. Use remove_radar_member for that.

  • Scope: radars:manage. Writes. Idempotent.
  • Required: radarId (UUID), email (a valid email address).
  • Returns: { "revoked": true }.

Withdrawing an invitation to co-own is refused for an agent.

set_radar_visibility

Makes a radar public (anyone with the link can read it) or private again. Theming never changes visibility. This is the only publish tool.

  • Scope: radars:manage, and you must be the owner. Writes.
  • Required: radarId (string), visibility (private or public).
  • Optional: allowSearchEngines (boolean): public radars ask search engines not to index them unless this is true. rotateLink (boolean): issue a fresh public URL and invalidate any link already shared.
  • Returns: id, visibility and publicUrl (null when private).

Publishing is refused for the drop box, for Helpdesk radars (including former Helpdesks) and for smart radars. rotateLink does not get round that. Publish only when the person has asked you to. See Public radars.

{ "radarId": "5b2c7e2e-1f0a-4a55-9a53-0d1f6f3b8a10", "visibility": "public", "allowSearchEngines": false }

Next