How it works

Transport

Streamable HTTP, stateless: each JSON-RPC request is one POST to the workspace URL. The server implements the current MCP specification and also answers clients on the previous protocol generation. There is no SSE side channel to keep open.

Authentication

The endpoint is an OAuth 2.1 protected resource.

1. An unauthenticated request gets 401 with a WWW-Authenticate: Bearer resource_metadata="…" challenge pointing at /.well-known/oauth-protected-resource/v1/mcp/{organizationId}.
2. The protected-resource document names the authorization server; its metadata is at /.well-known/oauth-authorization-server on the same origin.
3. The client registers itself (dynamic client registration is allowed) and starts an authorization-code flow with PKCE.
4. You sign in on the dashboard's login page and approve the consent screen. Google sign-in works the same way and lands back on the consent screen.
5. The client receives an access token bound to your account and presents it on every request.

Two checks run on each request after the token resolves: the account must be active, and it must hold an active membership in the workspace named by the URL. The token itself carries no workspace; the URL does. A 403 with "no active membership in the requested workspace" means the URL points at a workspace you are not in.

API keys (gi_sk_, gi_org_) and CLI sessions (geni_rs_) get the same 401 as no token. They belong to the REST API.

Sessions and the sandbox

Every member has one MCP thread per workspace. All of that member's conversations across every client share it, and it keys a persistent Linux sandbox. Files the agent writes under work/ survive from one tool call to the next and from one conversation to the next; the platform checkpoints that directory whenever a call changed it and restores it when the sandbox is replaced. Anything outside work/ is scratch and can vanish when the pod is recycled.

The sandbox is lazy, per request rather than per conversation. A request whose tools only read the database (searching docs, listing resources, reading executions) never starts a pod. The first tool that touches the filesystem adopts the existing pod or provisions a fresh one and seeds work/ from the checkpoint. That includes more than bash and the file tools: load_resource and load_skill write their files into the sandbox, so they provision one too.

Credentials

The agent never sees a secret. When it runs bash with a declared credential, the platform injects that credential's fields as environment variables into the subprocess and scrubs every registered secret value from the output. Each use is written to the workspace's credential access log with the reason the agent gave. The same discovery loop as the CLI applies: search the operation docs, find a connected credential, read the operation's reference, then write the call.

When a needed account is not connected, the connect tool returns a dashboard link. In hosts that render MCP Apps widgets it appears as a connect card with the service's logo; elsewhere it is a plain link. Connect in the browser, then ask again.

Resources

Creating a workflow, app, or skill runs inline. In the dashboard the create step shows a widget you approve; over the connector there is no such gate, so the resource is created the moment the tool is called and the agent goes on to edit its files in the sandbox and publish. Any confirmation you get is the assistant's own doing, not the platform's. Hosts that support widgets show a card linking to the new resource in the dashboard. Running a workflow starts a test execution in the background and returns its id; the agent polls the executions tools for the outcome. Human-in-the-loop pauses inside a run are answered in the dashboard, not the connector.

Files

Files the agent sends to you are uploaded to the workspace's file storage and returned as presigned download links, valid for seven days. The assistant relays the link.

Rate limits

The endpoint allows 1200 requests per minute. The bucket follows the caller's own credential rather than the source address, because a hosted connector such as claude.ai or ChatGPT calls from its own servers, where a single address fronts every customer using that connector. Your traffic is therefore yours alone, and one heavy user cannot exhaust another's allowance.

Billing

Sandbox wall-clock time and hosted-service calls made over the connector bill the workspace as MCP session usage, attributed to the member who signed in. Nothing bills until a sandbox starts or a paid service is called; browsing docs and resources is free.

Widgets

Hosts that implement MCP Apps (Claude, for one) render interactive cards for a few tools: connecting an integration, opening a resource the agent just created or updated, and integration actions. Hosts that do not simply show the text result. Widgets are additive; every tool returns a complete text result regardless.