Sess MCP server (@sess.si/mcp)

Let your agent ask a person and continue with their answer.

Install: add https://mcp.sess.si/mcp to your agent as an MCP server, and sign in to Sess when it asks.

Run: ask your agent "Ask me on my phone what time works for a call tomorrow, using Sess."

You'll see a Sess link in the reply: open it on your phone, answer, and your agent carries on with your answer.

Claude Code

Run this in your terminal:

claude mcp add --transport http sess https://mcp.sess.si/mcp

Claude Code opens Sess in your browser. Sign in and choose Allow. Using Sess on a second computer reconnects it there and disconnects the first.

Or run it on your machine. Put your Sess API key in SESS_API_KEY (from your Sess account, under API keys), then run this in the same terminal. Never paste the key into a chat.

claude mcp add --scope local sess -- npx -y @sess.si/mcp@0.2.0

Related MCP server: mcp-surveys

claude.ai

In Claude, open Customize, then Connectors, choose Add custom connector and paste:

https://mcp.sess.si/mcp

Claude opens Sess. Sign in and choose Allow.

ChatGPT

In ChatGPT, open Plugins, choose Add custom MCP server and paste:

https://mcp.sess.si/mcp

ChatGPT opens Sess. Sign in and choose Allow. Some ChatGPT plans allow only tools that read. Sess creates a link for you, so your plan needs to allow tools that make changes.

Grok

Grok Build: remote MCP

Run this in your terminal:

grok mcp add --transport http sess https://mcp.sess.si/mcp

Sign in to Sess when Grok Build asks, and choose Allow.

If it doesn't ask, type /mcps, select sess and press i.

Paste this into Grok Build:

Ask me on my phone what time works for a call tomorrow, using Sess.

Grok Build asks before it uses each Sess tool. Choose Always allow.

grok.com: Connectors

On grok.com/connectors, choose New Connector, then Custom, and enter:

https://mcp.sess.si/mcp

Sign in to Sess when Grok asks, and choose Allow.

Cursor

Paste this into Cursor's mcp.json (.cursor/mcp.json in a project, or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "sess": { "url": "https://mcp.sess.si/mcp" }
  }
}

Cursor opens Sess in your browser. Sign in and choose Allow.

Or run it on your machine. Put your Sess API key in SESS_API_KEY (from your Sess account, under API keys), then use this entry instead. Never paste the key into a chat.

{
  "mcpServers": {
    "sess": {
      "command": "npx",
      "args": ["-y", "@sess.si/mcp@0.2.0"],
      "env": { "SESS_API_KEY": "${env:SESS_API_KEY}" }
    }
  }
}

Antigravity

Put your Sess API key in SESS_API_KEY (from your Sess account, under API keys), then run this in your terminal:

agy mcp add sess npx -y @sess.si/mcp@0.2.0

Antigravity asks before it uses a Sess tool, usually once or twice the first time. Choose Allow, or Always allow if you'd rather not be asked again. Never paste the key into a chat. Sign in to Antigravity with your Google account, or use a Gemini API key.

OpenClaw

Sess asks you through your Claw. The agent gets four tools and uses them only when a decision is yours. OpenClaw uses the Sess plugin, @sess.si/openclaw, rather than this server.

1. Install. OpenClaw warns that the package comes from npm, not ClawHub. That is expected: Sess is published on npm with a signed build. Answer y.

   openclaw plugins install npm:@sess.si/openclaw@0.1.0 --no-enable
   openclaw sess setup --yes

2. Give the Gateway your key. It reads the key from its own environment file. Sess never stores it. The first line waits for you to paste the key and press Enter; nothing shows on screen.

   read -rs K && printf 'SESS_API_KEY=%s\n' "$K" >> ~/.openclaw/.env && unset K && chmod 600 ~/.openclaw/.env
   openclaw gateway restart

3. Ask. In any chat, say something like: Plan my weekend and check with me through Sess before you decide. Your Claw sends you a Sess link. Answer it on any device, then tell the chat to continue. The answer it uses is verified.

Check: openclaw sess doctor shows the setup without contacting Sess or printing your key.

Cline

In Cline, open MCP Servers, then Configure MCP Servers, and add this to cline_mcp_settings.json:

{
  "mcpServers": {
    "sess": {
      "type": "streamableHttp",
      "url": "https://mcp.sess.si/mcp"
    }
  }
}

When Cline connects, sign in to your Sess account in the browser. No key goes in the file.

Or run it on your machine with this entry instead. Type your Sess API key (from your Sess account, under API keys) into the file yourself, in place of your Sess API key. Never paste the key into a chat.

{
  "mcpServers": {
    "sess": {
      "command": "npx",
      "args": ["-y", "@sess.si/mcp@0.2.0"],
      "env": { "SESS_API_KEY": "your Sess API key" }
    }
  }
}

Your own agent

Connect your MCP client to the hosted server over Streamable HTTP. It signs in with your Sess account.

https://mcp.sess.si/mcp

Or add this as a local MCP server in your agent:

npx -y @sess.si/mcp@0.2.0

Your agent asks before it starts the server. The server reads your Sess API key from the SESS_API_KEY environment variable; never paste it into a chat.

No MCP? Add Sess to your agent shows a tool and handler on the Sess SDK for an agent you build on a model API.

First interaction: approve before acting

Have your agent check with you before it commits a change or sends a reply. Ask it something like:

"Before you commit, use Sess to show me what changed and the commit message. Wait for my approval and commit with the message I approve."

The agent calls sess_request and shows you a Sess link at once. Open it on your phone. You see what changed, and the proposed message in a field you can edit. Change a line if you like, then approve, or stop. The agent waits with sess_response and continues only on the verified answer: it commits with the message you approved, or does nothing if you stopped. If you are slower than its 45-second wait, it checks again for about two minutes, then tells you the form is still open; answer it and say continue.

The same works for a reply: "Before you send this reply, use Sess to show me the draft so I can edit and approve it."

A synthetic sample of what the agent sends (sample content, not from a real repository):

{
  "mode": "interactive",
  "title": "Approve this commit?",
  "source": {
    "kind": "sess_surface",
    "components": [
      {
        "type": "record",
        "label": "What changed (sample)",
        "fields": {
          "src/greeting.js": "Greeting now uses the user's first name",
          "test/greeting.test.js": "One new test for the first-name greeting"
        }
      },
      {
        "type": "field",
        "name": "message",
        "label": "Commit message",
        "multiline": true,
        "schema": { "type": "string", "minLength": 1, "maxLength": 2000 },
        "value": "Greet users by first name\n\nAdds a test for the new greeting."
      }
    ]
  },
  "actions": [
    { "id": "approve", "label": "Approve and commit", "intent": "approve" },
    { "id": "stop", "label": "Stop", "intent": "reject" }
  ]
}

Text blocks are shown as plain paragraphs, so send a summary of the change rather than a raw diff; line breaks are kept in multiline fields.

Tools (sess-mcp-tools/5)

After an answer, sess_complete is the rule, not an option: when sess_response returns state answered and the agent has no follow-up question for the person, it must call sess_complete next, so the person's page shows that the agent has their answer. Until then the page keeps waiting for the next step. Only to show a follow-up does the agent call sess_publish instead. The server instructions and both tool descriptions say this.

While there is no answer yet, the host calls sess_response again, up to three times after its first call (about two minutes more at the 45-second ceiling), then asks the person to say continue. The server instructions, the sess_response description and the text of a waiting or needs_resume result say this. The server keeps no count; the host does.

sess_ask is a shortcut for sess_request: it turns a question and up to 12 simple fields (text, number, integer, boolean, choice, multi_choice, rating) into an ordinary interaction, checks it with the same rules and limits, and runs the same request operation. It creates exactly one Session, returns the link and handle at once, never waits and never returns an answer. Continue with sess_response, sess_publish and sess_complete as usual.

Advanced: expires_in sets how long the link stays open, in whole seconds from creation: from 30 up to your plan's link lifetime (Sess checks the ceiling). The result's expiresAt is when the link stops taking answers, as created; on a link of 20 hours or less the person may ask for more time, up to a fixed horizon. While the link is lapsed (past that time but still extendable) sess_response reports waiting. It reports expired once the link has closed for good with no answer: it is final, and nothing was completed. An answer accepted before the end is still returned as answered.

Advanced: respondents: { max } on sess_ask asks many people through one link (a Sess Ask): share the link with everyone who should answer; each person gets their own page. A respondent is a browser, not a person. The cap is exact: it is checked when a person starts, so it cannot be overshot. respondents also takes name (a required "Your name" field), expires_in (the one deadline, instead of the top-level expires_in) and respondent_expires_in; each person's page completes when their answer is accepted. The result carries interaction.ask.id. sess_response on that handle reads once, without waiting, and returns interaction.ask: whether it is open, the counts, and each person's verified answer so far. Its state is waiting while answers may still come and closed once none can. sess_publish and sess_complete refuse an Ask's handle.

Input schemas are closed: unknown properties, unsafe keys (__proto__, constructor, prototype), more than 8 levels of nesting, an interaction over 32 KiB, more than 24 fields or 5 actions are rejected, never truncated. interaction is the Sess interactive Surface used by @sess.si/sdk (heading, text, record and field components). Tools never accept an API origin, key, workspace, Session ID or callback URL.

Keep it short

A person reads the form on a phone. Every field a person reads carries its purpose, style, limit and examples in the tool schema, and sess_ask's description carries one complete good call. Lengths are Unicode code points:

A choice without an option_labels entry shows its enum ID, so that ID is held to 60 too (named at its enum entry, e.g. /interaction/source/components/2/schema/enum/1); a long ID with a short label is fine.

A value over its limit is refused before anything is sent or saved, never truncated, with INVALID_ARGUMENTS and the value's field (a JSON pointer into the arguments, such as /question or /interaction/actions/0/label; for a record key it ends with that key), the limit and its length. The message is Sess's own: the title has "The title can be at most 80 characters. Keep it to a short heading, about 40."; anything else names its pointer:

{
  "error": {
    "code": "INVALID_ARGUMENTS",
    "message": "/fields/0/label is 72 characters; the limit is 60. Shorten it to at most 60 characters.",
    "retryable": false,
    "field": "/fields/0/label",
    "limit": 60,
    "length": 72
  }
}

Shorten that value and call the tool again. If Sess itself refuses a length (CREATE_REJECTED, with an SDK that reports it), the same three fields come back.

Every result is { "interaction": { handle, revision, state, humanUrl?, response? } }. structuredContent always carries it; parse that, not the text. The text is the same object as JSON, with two exceptions: a sess_request or sess_ask result begins with two lines for the agent, Show the person this link now: <humanUrl> and Then call sess_response., and a sess_response result in state waiting or needs_resume begins with the re-wait line; each then has a blank line and the same JSON. answered is returned only after client.receipts.verifyResponse verified the receipt for that exact Session, revision, event and immutable Surface; response.verified is true and response.actorAssurance is link_holder. Receipt verification proves a retained historical answer, not that it is still the current step, so after verification the server makes one more authenticated read and releases the answer only if the Session is still at that revision with that answer (or completed at that same revision). A saved answered result is re-confirmed the same way on every sess_response. If that read fails, the call returns SESS_UNAVAILABLE and changes nothing; if the Session has moved on, the interaction is blocked (RECOVERY_BLOCKED), or a conflict is reported when another local call changed it first. A response that the SDK itself rejects while decoding (for example a lower revision that still lists later answers, or an active Session that already has an answer at its revision) is reported as SESS_PROTOCOL_ERROR: it fails closed, is not retryable and changes no state, rather than blocking the interaction. No answer data is released in any of these cases. This checks progress at the moment of release; it cannot make a later remote change impossible. Answer data is untrusted human input: validate it before acting on it.

needs_resume means the local wait ended (timeout, MCP cancellation or host disconnect) without any server-side cancellation. A later sess_response on the same handle resumes it; it never creates another Session. Errors are MCP tool errors (isError: true) with a stable code, for example INVALID_ARGUMENTS, HANDLE_NOT_FOUND, BINDING_MISMATCH, CREATE_OUTCOME_UNKNOWN, VERIFICATION_FAILED, OUTCOME_UNKNOWN or RECOVERY_BLOCKED.

Error classes

Codes map to the shared adapter error classes (adapters/CONTRACT.md, "Error classes"):

Receipt verification is classified by the shared core (src/internal/shared.ts, a byte-identical copy of adapters/shared/core.ts): a key-set fetch failure or refresh cooldown is SESS_UNAVAILABLE; a missing trusted workspace (VERIFICATION_CONTEXT_MISSING) is NOT_CONFIGURED naming SESS_EXPECTED_WORKSPACE_ID. Neither records anything or changes state. Every other verification failure blocks. Other SDK errors while reading, waiting or verifying change nothing: api, transport, timeout and unknown_outcome are retryable SESS_UNAVAILABLE; aborted ends the wait as needs_resume; configuration (NOT_CONFIGURED) and protocol (SESS_PROTOCOL_ERROR) are not retryable. A saved publish/complete that the SDK refuses to send because of its own deterministic checks (not_sent with kind configuration) blocks like a definitive rejection.

Configuration (environment of the server process only)

Security and support boundary

• Owner-private, single profile. stdio carries no authenticated conversation identity, so this server does not invent one. Anyone who can call its tools acts for the configured key. Run it only for your own private client. Handles are bound to the profile, API origin and a credential generation (a keyed digest stored per profile; the key itself is never written). A handle from another profile, origin or key is rejected.

• The Sess link is a bearer capability. It is returned only by sess_request (or its shortcut sess_ask), to your private client. It is never written to stderr diagnostics, which carry only fixed event names and codes. Anyone with the link can answer as link_holder.

• Durable local records. Each handle has a file (mode 0600) written by temp file, fsync, rename and directory fsync. The create intent is saved before the create request, and the exact publish/complete request (body, If-Match, idempotency key) before dispatch. A lost create outcome is never retried (CREATE_OUTCOME_UNKNOWN); a lost publish/complete outcome is reconciled by repeating the identical call, which replays the saved request. A replay of an already confirmed publish or complete succeeds only with the identical expected revision and body; anything else is refused without a request. A deterministic rejection (for example a conflict or validation error) moves the record to blocked. blocked and create_unknown records need owner review; the server never leaves those states on its own (see below). If a confirmed create cannot be saved locally, CREATED_NOT_SAVED says not to repeat the request. After completion the link and answer data are removed from this server's own local record; that clears its copy only, and the hosted Session and receipt follow their own retention. At most 100 unfinished interactions are kept per profile.

• No wake-up. A wait is one bounded read of at most 45 seconds. The host is told to call again up to three times, then stop. The server cannot wake an agent after its turn ends; the person says continue.

• Not in this package: an HTTP server or bin flag, a hosted server, OAuth, MCP Tasks, Apps, elicitation, resources or prompts (the HTTP composition below is a library for a hosting runtime, not a runnable server). One server process per profile is supported; concurrent processes on the same profile are not coordinated. Rotating the key makes earlier handles unusable (BINDING_MISMATCH).

• Receipt-key rotation window. The SDK refreshes its cached receipt key set at most once per 10 seconds. If Sess starts signing with a new key and an answer signed with it is verified within 10 seconds of this server's previous key-set fetch, the SDK reports UNKNOWN_KEY_ID, and the interaction is blocked (VERIFICATION_FAILED) even though the answer may be valid. Use the owner procedure below; fixing this needs an SDK change.

HTTP composition (library for a hosting runtime; not a deployed endpoint)

@sess.si/mcp/http exports createSessMcpHttpHandler(options), a stateless Streamable HTTP handler for the same five tools. It is built on createMcpHandler from @modelcontextprotocol/server with its default stateless legacy fallback, so one endpoint serves 2026-07-28 clients and 2025-era clients (initialize answers 2025-11-25; no session ID). Each request gets a fresh server and adapter. Nothing in this package starts a listener; the hosting runtime mounts handler.fetch (web-standard) or handler.node (node:http).

The hosting runtime supplies the authority; this package never decides it:

• authenticate(request) (required) sees the method, URL and headers, verifies the request's credentials and returns a principal context: workspaceId, principalId, clientId, grantId, grantGeneration, scopes and a credential() provider for Sess API calls. If it returns nothing, the answer is 401 with WWW-Authenticate: Bearer resource_metadata="…"; a principal without every requiredScopes entry gets 403 insufficient_scope. The handler never derives authInfo from headers and never sends the MCP bearer token to Sess or to a tool.

• handleStore(binding, principal) (required) returns a handle store bound to that authority. Handles are bound to origin, workspace, principal, client, grant and grant generation: another principal, host or workspace gets HANDLE_NOT_FOUND; a revoked or re-issued grant (new generation) gets BINDING_MISMATCH; a token refresh (same generation) keeps the handles. The operations re-check every loaded record, whatever the store does. The durable hosted store is not in this package.

In front of the SDK entry, in this order on both faces:

1. A header-only preflight before any body byte is read: the Host allowlist (required), an exact Origin allowlist (requests without Origin, as non-browser clients send them, are accepted), then exactly one authenticate call and the scope check. A rejection is answered at once, even while the client is still sending; the Node face then closes the connection.

2. A bounded body (default 256 KiB: a larger declared Content-Length or streamed body gets 413; non-JSON gets 415 from the SDK) read under the request deadline.

3. The raw-body unsafe-key guard, answered in the request's protocol era.

The deadline (requestTimeoutMs, default 60 s) is absolute from the moment the request enters the handler. A body that has not arrived by then gets 408 and reading stops (the Node face closes the connection); an authenticate hook that has not answered gets 503. During tool execution the same deadline ends an in-flight sess_response wait as needs_resume; a create, publish or complete already sent is never abandoned mid-flight. The timer is cleared when the response completes or fails, or when the client disconnects. The Sess link is returned to the agent in the tool result exactly as over stdio and never appears in diagnostics.

Resolving a blocked or unconfirmed interaction (owner procedure)

The tool error names the state (RECOVERY_BLOCKED with a reason, CREATE_OUTCOME_UNKNOWN or CREATED_NOT_SAVED). The server never repairs these records itself.

1. Find the record: <state dir>/profiles/<profile>/handles/<handle>.json. It can contain the Sess link and answer data; do not paste it into chats or issues.

2. Check the Session in Sess (developer portal or an owner API read using sessionId from the record, when present). For create_intent/create_unknown/CREATED_NOT_SAVED, look for a Session created at that time before asking the agent to create another one.

3. Decide in Sess what should happen to the Session, then remove the local record file to retire the handle. Keep a private copy if you need the evidence. There is no command that resumes a blocked handle in this version; start a new interaction with sess_request if needed.

Development

The adapter is an independent package with its own lockfile. package.json always declares the exact SDK version from the repository's single pin, release/sdk-candidate.json (name, version, filename, SHA-256, SHA-512). package-lock.json is a maintainer file only; npm never ships it to consumers. The lock resolves the SDK to the genuine npm registry tarball (https://registry.npmjs.org/@sess.si/sdk/-/sdk-0.2.0.tgz, dist-tag latest) with the pinned integrity, so no local SDK build or pack is needed. compatibility.json mirrors the pin; npm run pin:update at the root keeps both, the lockfile and the dependency in step after a deliberate change, and the root npm run check fails on drift.

cd adapters/mcp
npm run setup    # npm ci from the registry; refuses a lock that is not the registry SDK
npm run check    # SDK identity and digests, build, typecheck, unit tests, packed-consumer check

npm run check starts with npm run sdk:verify: the lock and the installed SDK must be the registry tarball with the pinned integrity, and the registry tarball is read again and its SHA-256 and SHA-512 compared with the pin.

A future, not yet published SDK pin

The digest-gated candidate path is kept only for a pin that is not on npm yet: npm run candidate:prepare packs the repository root with scripts/sdk-pin.mjs pack and accepts the tarball into the gitignored .candidate/ only if its digests equal the pin (npm does not enforce lock integrity for file: tarballs), and npm run candidate:verify accepts either mode. npm run setup, npm run check, CI and releases refuse candidate mode. Once that pin is published:

npm run sdk:switch-to-registry            # dry run: confirms the registry integrity equals the pinned one
npm run sdk:switch-to-registry -- --apply # npm install --save-exact, lock check, re-download + SHA-256 check
npm run check

--apply runs npm install --save-exact --ignore-scripts @sess.si/sdk@<pinned version>, requires the regenerated lock entry to be the registry tarball with the pinned integrity, downloads the published tarball again and compares its SHA-256 with the pin, and records the published status in compatibility.json. It refuses any other bytes. Review and commit the lockfile change.

npm run runtime-round (opt-in, SESS_MCP_RUNTIME_ROUND=1) drives the packed, installed server through one request → answer → complete round against a local isolated Sess runtime. It is not run in public CI because the runtime is private. npm run qualify:claude-code checks that Claude Code connects and lists the tools without any model call, using a temporary config directory.

Which hosts and versions Sess has run, and what is still untested: COMPATIBILITY.md.

Apache-2.0