On My Radar
On this page

Guides Agents and MCP

MCP reference

How the On My Radar MCP server works, how it authenticates, which scope each of its 99 tools needs, the conventions they share, and an index of the tool pages.

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

This page explains how the On My Radar MCP server behaves and what every tool has in common, so you can read the tool pages without repeating it. After it you will be able to connect an agent, know which scope a tool needs, and find the page for any of the 99 tools.

For a first-time setup, start with Connect your agent. For a worked example, see the agent workflow walkthrough.

How the server works

The MCP server lives at /mcp on your On My Radar address. For onmyradar.io that is https://onmyradar.io/mcp. Settings, Connections shows the exact URL for your account and has a copy button.

  • An agent acts as you. It can reach exactly the radars you can reach, with at most your permissions. Nothing else.
  • It is stateless and POST only. Each request builds a fresh server. GET /mcp and DELETE /mcp answer 405, for everyone, because there is no stream to open and no session to resume. A 405 there is not a failure. The old HTTP+SSE transport is not implemented, so /mcp/sse and /mcp/messages answer 404.
  • Every tool is a thin wrapper over the same code the app uses. The same access checks run, so a tool cannot do something the app would refuse you.
  • Your plan decides whether MCP is available. If your plan does not include an AI connection, calls are refused with a message pointing you to Plans & billing. Which plans include it depends on your plan, so this reference does not say. An operator can also switch MCP off for a whole server, in which case /mcp answers 404.
  • Resources and a prompt. Besides tools, the server offers read-only resources: onmyradar://radars (an index of radars you can read), onmyradar://capabilities (the same inventory as list_capabilities), onmyradar://agents, onmyradar://agents/{agent} (an agent's prompt) and onmyradar://agents/{agent}/memories/{name} (one memory). It also offers a prompt named agent that loads an agent for a conversation. None of these are tools and they are not counted below.

Connecting and authenticating

There are two ways to connect.

A personal access token, for a local agent.

  1. Open Settings, then Connections.
  2. Under Access tokens, choose New token. The dialog is titled "New access token".
  3. Under Connection permissions, tick the scopes this agent should have. Name the token after the tool that will use it, then choose Create token.
  4. Copy the secret. It is shown once. Tokens start with omr_pat_.
  5. Add it to your client as a bearer token. For Claude Code:
claude mcp add --transport http onmyradar https://onmyradar.io/mcp --header "Authorization: Bearer omr_pat_xxxx"

Any MCP client that supports streamable HTTP with a bearer token works the same way. Revoke a token from the same screen and it stops working immediately.

OAuth, for remote clients such as claude.ai. The client needs only the URL. On My Radar is its own authorization server, so the client discovers the sign-in flow from the 401 that an unauthenticated POST /mcp returns. You see a consent screen naming the client before any token is issued. It is never approved automatically.

Details on tokens, scopes and revoking access are in Tokens, scopes and revocation.

Scopes

A connection has a ceiling. Effective access is the weaker of what you can do and what the connection was granted, so a scope can only take away. A token can never reach a radar you cannot reach.

There are three scopes, and each includes the ones before it.

  • radars:read: "Read and search everything you can see". It also covers your agents' prompts and memory.
  • radars:write: "Capture and file blips, and make new radars". It adds editing, commenting, reacting, creating radars, topics and dashboards, saving agent memory and editing agent prompts.
  • radars:manage: "Publish radars and change who they are shared with". It adds deleting radars, moving them between topics, and managing their webhooks and feeds.

A client that asks for nothing gets all three. A client that asks for less gets only what it asked for. Because a scope is a single ceiling, "manage without write" is not possible.

The scope a call needs is the lowest one that covers it. A call above the connection's ceiling fails with a sentence such as "This connection was not granted radars:manage." That differs on purpose from "you have read-only access to this radar", which is about your account. Only re-authorizing the connection fixes the first. whoami reports the scopes a connection holds.

Every connection holds at least radars:read, so a tool that checks no scope works with any connection.

Tools that need radars:read (40):
whoami, list_capabilities, describe_templates, get_notification_settings, list_radars, read_radar, list_topics, read_topic, list_topic_members, list_radar_members, list_dashboards, preview_dashboard_query, read_dashboard_widget, search_blips, search_suggestions, read_architecture, trace, get_blip, get_blip_reminder, list_tags, read_drop_box, list_comments, list_notifications, get_email, download_original_email, read_attachment_image, download_attachment, list_integrations, list_integration_deliveries, list_agents, load_agent, agent_recall, list_agent_prompt_versions, get_agent_prompt, get_agent_profiles, list_agent_briefs, get_agent_brief, agent_activity, checkout_agent, export_agent.

Tools that need radars:write (33):
create_radar, create_smart_radar, create_topic, create_blip, update_blip, delete_blip, drop, create_comment, update_comment, delete_comment, react_to_blip, create_upload_ticket, create_dashboard, update_dashboard, delete_dashboard, mark_notifications_read, mark_notifications_seen, unenroll_helpdesk_radar, pause_integration_delivery, propose_adr, decide_adr, upsert_boundary, upsert_contract, agent_remember, agent_forget, create_agent, update_agent, update_agent_prompt, set_agent_profile, delete_agent_profile, update_agent_brief, rename_agent_brief, import_agent.

Tools that need radars:manage (25):
delete_radar, set_radar_theme, set_radar_lanes, set_radar_visibility, share_radar, share_topic, update_topic, delete_topic, set_radar_topic, remove_radar_member, revoke_radar_invite, remove_topic_member, revoke_topic_invite, list_webhooks, create_webhook, update_webhook, rotate_webhook_secret, delete_webhook, list_subscriptions, delete_subscription, list_subscription_deliveries, list_feeds, create_feed, update_feed, delete_feed.

Two tools depend on what you change. update_radar: presentation fields (tagline, description, accent, glyph) need radars:write, and structural fields (name, archiving, topic, template, lanes, a smart radar's filter, comment and reaction switches, archive window, theme) need radars:manage. update_agent is listed above under radars:write, but changing the agent's slug (its @handle) needs radars:manage and ownership of the agent.

Note: Holding radars:manage does not let an agent do everything an owner can. Some acts are refused at any scope because they are a person's decision: turning a topic's cascade on or off, sharing a cascading topic, granting owner, changing notification settings, inviting an address with no account, and the agent decisions listed on the agents tool page. The refusal says what to ask the person to do.

Conventions

Ids. Ids are UUIDs and are passed exactly as a list or search tool returned them. Some tools take radarId as a plain string because it may also be a radar's public link slug, for example read_radar. An argument typed as a UUID that holds anything else is rejected by validation, naming the field. In an argument that takes a plain string, such as radarId on read_radar, a malformed id can instead be answered with "Not found: an id in the request is not a valid id."

Not found, not forbidden. A radar you cannot read is reported as not found. The error never confirms that it exists.

Pagination. Tools that page return nextCursor. Pass it back unchanged as cursor, with the same filters, to get the next page. A null nextCursor means you have everything. A cursor is an opaque string of letters, digits, hyphens and underscores, up to 1,024 characters. Page sizes differ by tool.

  • read_radar, search_blips and read_drop_box: limit 1 to 200, default 50.
  • list_comments: 1 to 100, default 50.
  • list_notifications: 1 to 100, default 30.
  • agent_recall: 1 to 100, default 20. agent_activity: 1 to 100, default 50. list_agent_prompt_versions: 1 to 50, default 50.
  • get_email pages by character offset and limit instead, and returns nextOffset.

Do not re-sort. read_radar returns blips in the order the radar's template means: a reading list as a queue, a decision log with what is live first, everything else newest first.

Long text is cut in lists. List and search results cut bodies at 1,200 characters and mark them bodyTruncated. Use get_blip for the whole text.

Dates. Timestamps such as dueAt and updatedSince are ISO 8601 with an explicit UTC offset.

Attribution: as and session. create_blip, update_blip, drop, create_comment and update_comment accept as (me or agent) and session (the id load_agent returned). A write made under an agent records both the agent and the person who cosigns it, and as only chooses which name leads. Asking for a voice the connection was not granted is refused, and so is as: "agent" on a connection that is running no agent. whoami shows voice.granted and voice.default. See Agents, sessions and attribution.

Read-only versus write. Read tools carry a read-only hint, and a tool without one writes. Most tools that delete carry a destructive hint, and several carry an idempotent hint, meaning a retry does not repeat the effect. Not every tool that changes or replaces something carries a destructive hint, so do not use the hint to decide whether a write is safe. Each tool page says what applies. react_to_blip and pause_integration_delivery are safe to retry. rotate_webhook_secret is not: every call issues a new URL.

Results. Most results are JSON text in a single text block. Two tools differ: load_agent returns several text blocks of Markdown, and read_attachment_image returns a short text notice followed by an image block. No tool returns a separate structured copy, so a client always sees the same content. Text a client typed into the portal on a Helpdesk radar is wrapped in a marker saying it is client data, not instructions. Treat it that way.

Errors. A refusal comes back as a tool result with isError set and one plain sentence. There are four kinds: a validation message naming the field, a deliberate refusal written to be read (for example "Only the owner can do that" or a missing scope), the malformed-id message above, and a generic "That failed on the server" message with an error id for anything unexpected. Server details are never sent to the agent. At the HTTP level, an unauthenticated call gets 401 with a WWW-Authenticate header, a suspended or otherwise unavailable account gets 403, and an unparseable body gets 400.

Cached tool lists. MCP clients may cache the tool catalog. If a tool or argument described here is missing, refresh or reconnect.

Tool index

All 99 tools appear exactly once in the pages below.

  • Capture, edit and discuss (10): create_blip, update_blip, delete_blip, drop, create_upload_ticket, list_comments, create_comment, update_comment, delete_comment, react_to_blip.
  • Read, search and fetch (11): read_radar, read_drop_box, search_blips, search_suggestions, list_tags, get_blip, get_blip_reminder, get_email, download_original_email, read_attachment_image, download_attachment.
  • Radars, templates and architecture (14): list_radars, create_radar, update_radar, create_smart_radar, delete_radar, describe_templates, set_radar_lanes, set_radar_theme, read_architecture, propose_adr, decide_adr, upsert_boundary, upsert_contract, trace.
  • Topics, sharing and publishing (15): list_topics, read_topic, create_topic, update_topic, delete_topic, set_radar_topic, share_topic, list_topic_members, remove_topic_member, revoke_topic_invite, share_radar, list_radar_members, remove_radar_member, revoke_radar_invite, set_radar_visibility.
  • Dashboards and RSS feeds (10): list_dashboards, create_dashboard, update_dashboard, delete_dashboard, preview_dashboard_query, read_dashboard_widget, list_feeds, create_feed, update_feed, delete_feed.
  • Agents, prompts, memories and briefs (21): list_agents, load_agent, agent_recall, agent_remember, agent_forget, create_agent, update_agent, update_agent_prompt, list_agent_prompt_versions, get_agent_prompt, get_agent_profiles, set_agent_profile, delete_agent_profile, list_agent_briefs, get_agent_brief, update_agent_brief, rename_agent_brief, agent_activity, checkout_agent, import_agent, export_agent.
  • Webhooks, integrations, notifications and account (18): list_webhooks, create_webhook, update_webhook, rotate_webhook_secret, delete_webhook, list_subscriptions, list_subscription_deliveries, delete_subscription, list_integrations, list_integration_deliveries, pause_integration_delivery, unenroll_helpdesk_radar, list_notifications, mark_notifications_read, mark_notifications_seen, get_notification_settings, whoami, list_capabilities.

How this reference was derived

The tool pages were written from the server's own tool registrations: each tool's name, description, input schema, annotations and the access check it runs. They were cross-checked against the project's MCP documentation. Where the two disagreed, the code was followed.

The live server is authoritative. list_capabilities and your client's live tool list show the current arguments, and they can change after this page was written. If something here does not match what your client shows, trust the client.

Next