Skip to content
Instant

Developers

Agents and Agents

Instant has a standard MCP server, so any agent or agent that speaks MCP can work in a workspace as one person, with that person’s access and no more. This page is the reference. If you just want to connect Claude, ChatGPT or Cursor, start here instead.

The Address

https://mcp.instant.im

Streamable HTTP, JSON-RPC over POST. It answers the 2026-07-28 revision of the Model Context Protocol and the earlier ones back to 2024-11-05, on the same address. Every request carries its own token, so there is no session to keep. With Claude Code:

claude mcp add --transport http instant https://mcp.instant.im/mcp

Signing In

OAuth 2.1 with PKCE. There is no API key to copy. A client finds everything it needs from the standard discovery documents:

https://mcp.instant.im/.well-known/oauth-protected-resource
https://mcp.instant.im/.well-known/oauth-authorization-server
  • Registering. Dynamic Client Registration, or a Client ID Metadata Document (an https URL as the client id). No approval step.
  • Consent. The person signs in to Instant, picks one workspace and chooses what the agent may do. One connection covers one person in one workspace.
  • Tokens. Access tokens last an hour. Refresh tokens are swapped for a new one on each use and last 30 days unused. Only hashes are stored.

Permissions

PermissionScopeWhat It Allows
ReadreadSearch and read what the person can read. Always part of a connection.
See Who’s AroundpresenceWho is in the office, in a room or on a call.
Write Messagesmessages:writePost, reply, react, check in and set status as the person.
Write to the Wikidocs:writeCreate and add to Wiki pages, and tick off action items.
Meetings and Wavesmeetings:writeSchedule meetings with teammates and wave at people.

An agent never gets more than its person has. On top of that:

  • Guests can’t connect agents.
  • Channels marked Keep Agents Out, and restricted Wiki sections, are closed to every agent.
  • Admins can turn off agents, writing, or reading DMs for the whole workspace. It takes effect on the next request.
  • Members, roles, billing, settings, invites, exports and the audit log can’t be reached at all.
  • An agent can’t use @channel, invite outside email addresses, or edit and delete anything it didn’t send itself.

Tools

ToolNeedsWhat It Does
searchReadSearch messages, threads, meeting notes, docs and the Wiki, by meaning or by words.
fetchReadOpen one result in full: a message with its thread, a page, a doc or meeting notes.
catch_upReadWhat needs the person: mentions, DMs, replies and what they missed.
recapReadSum up a channel or thread over a period.
askReadAsk a question and get an answer with sources from the Wiki and conversations.
read_conversationReadRead recent messages in a channel, DM or thread.
list_conversationsReadThe channels and DMs the person is in, with unread counts.
find_peopleReadLook people up by name, role or team.
list_meetingsReadUpcoming meetings and recent meeting notes.
my_workReadOpen action items, reminders, saved messages and standups due.
browse_wikiReadThe Wiki’s sections and pages.
who_is_aroundSee Who’s AroundWho is in the office, in which room, on a call or away.
send_messageWrite MessagesPost or reply as the person. Shows “via” and the agent’s name.
edit_messageWrite MessagesEdit a message this agent sent.
delete_messageWrite MessagesDelete a message this agent sent.
reactWrite MessagesAdd or remove a reaction.
create_pollWrite MessagesStart a poll in a channel.
check_inWrite MessagesPost the person’s standup.
set_statusWrite MessagesSet or clear the person’s status.
remind_meWrite MessagesSet a reminder on a message.
waveMeetings and WavesWave at a teammate with a short note.
schedule_meetingMeetings and WavesSchedule a meeting and invite teammates.
add_to_wikiWrite to the WikiCreate a Wiki page or add to one.
complete_action_itemWrite to the WikiTick off an action item in meeting notes.

Everything an agent posts is the person’s own message with a label beside their name: “via Claude”, “via ChatGPT”, or whatever the agent calls itself when it signs in. Tools take names (“#design”, “Ada Lovelace”) as well as ids.

Ready-Made Requests

The server offers prompts that show up as shortcuts in agents that support them: catch_me_up, write_my_standup, prep_my_next_meeting, what_did_we_decide and write_it_down.

Limits

  • 120 requests a minute for each connection.
  • About 2,000 items read an hour, and 60 changes an hour. Past either, the tool answers rate_limited until the hour moves on.
  • The person sees what each of their agents did under Settings › Connect Your Agent. Instant keeps what was done, never what was read.

Live Updates

An agent that runs on its own shouldn’t have to keep asking. With Live Updates, Instant sends it a signed request the moment something needs its person: a mention, a DM, a reply in their thread, one of their keywords, a wave or a reminder.

  1. Connect the agent as usual, so it shows under Connected Apps.
  2. Open its Activity, then Live Updates. Copy the signing secret into your agent.
  3. Enter a public https address and choose Turn On. Instant checks it first by sending a challenge, which your address must send back.

An update

POST https://your-agent.example/instant
x-instant-signature: v0=…
x-instant-request-timestamp: 1795229087

{
  "type": "event_callback",
  "event_id": "ev_…",
  "event_time": 1795229087,
  "team_id": "ws_…",
  "api_app_id": "cg_…",
  "authorizations": [{ "team_id": "ws_…", "user_id": "usr_…", "is_bot": false }],
  "event": {
    "type": "inbox_item",
    "reason": "mention",
    "title": "Ada Lovelace mentioned you in #design",
    "preview": "Can you look at the pricing page today?",
    "user": "usr_…",
    "channel": "ch_…",
    "ts": "msg_…",
    "fetch_id": "message:ch_…:msg_…",
    "url": "https://instant.im/w/acme/c/ch_…",
    "event_ts": "2026-11-21T02:44:47.000Z"
  }
}

reason is one of mention, dm, reply, keyword, wave or reminder. thread_ts is there for a reply. Hand fetch_id to the fetch tool to read the message and its thread in full.

Requests are signed exactly like bot events, so the same check works:

Check the signature

import { createHmac, timingSafeEqual } from 'node:crypto';

function fromInstant(req, rawBody) {
  const ts = req.headers['x-instant-request-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const mine = 'v0=' + createHmac('sha256', process.env.INSTANT_SIGNING_SECRET).update(`v0:${ts}:${rawBody}`).digest('hex');
  const theirs = String(req.headers['x-instant-signature']);
  return mine.length === theirs.length && timingSafeEqual(Buffer.from(mine), Buffer.from(theirs));
}
  • Only the person can set it. The address is set in the app, never by the agent, and nobody else can see it or the secret, admins included.
  • The same walls apply. Nothing is sent from Keep Out channels, from DMs when the workspace keeps agents out of DMs, or once the connection or the workspace switch is off.
  • It follows the person’s notification settings, except quiet time and Focus, which hold things back from people, not from their agents.
  • Answer within 3 seconds with any 2xx. A failed delivery is tried once more. After 50 failures in a row updates pause until the address is saved again. If you miss something, catch_up has it.
  • Updates stop when the connection hasn’t been used or renewed for 30 days.

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing