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.imStreamable 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/mcpSigning 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
| Permission | Scope | What It Allows |
|---|---|---|
| Read | read | Search and read what the person can read. Always part of a connection. |
| See Who’s Around | presence | Who is in the office, in a room or on a call. |
| Write Messages | messages:write | Post, reply, react, check in and set status as the person. |
| Write to the Wiki | docs:write | Create and add to Wiki pages, and tick off action items. |
| Meetings and Waves | meetings:write | Schedule 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
| Tool | Needs | What It Does |
|---|---|---|
search | Read | Search messages, threads, meeting notes, docs and the Wiki, by meaning or by words. |
fetch | Read | Open one result in full: a message with its thread, a page, a doc or meeting notes. |
catch_up | Read | What needs the person: mentions, DMs, replies and what they missed. |
recap | Read | Sum up a channel or thread over a period. |
ask | Read | Ask a question and get an answer with sources from the Wiki and conversations. |
read_conversation | Read | Read recent messages in a channel, DM or thread. |
list_conversations | Read | The channels and DMs the person is in, with unread counts. |
find_people | Read | Look people up by name, role or team. |
list_meetings | Read | Upcoming meetings and recent meeting notes. |
my_work | Read | Open action items, reminders, saved messages and standups due. |
browse_wiki | Read | The Wiki’s sections and pages. |
who_is_around | See Who’s Around | Who is in the office, in which room, on a call or away. |
send_message | Write Messages | Post or reply as the person. Shows “via” and the agent’s name. |
edit_message | Write Messages | Edit a message this agent sent. |
delete_message | Write Messages | Delete a message this agent sent. |
react | Write Messages | Add or remove a reaction. |
create_poll | Write Messages | Start a poll in a channel. |
check_in | Write Messages | Post the person’s standup. |
set_status | Write Messages | Set or clear the person’s status. |
remind_me | Write Messages | Set a reminder on a message. |
wave | Meetings and Waves | Wave at a teammate with a short note. |
schedule_meeting | Meetings and Waves | Schedule a meeting and invite teammates. |
add_to_wiki | Write to the Wiki | Create a Wiki page or add to one. |
complete_action_item | Write to the Wiki | Tick 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_limiteduntil 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.
- Connect the agent as usual, so it shows under Connected Apps.
- Open its Activity, then Live Updates. Copy the signing secret into your agent.
- 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_uphas it. - Updates stop when the connection hasn’t been used or renewed for 30 days.