--- name: scrollport-start description: >- Set up Scrollport through the safest route this environment can retain: an existing connection, CLI-managed credentials, remote MCP OAuth, or direct HTTPS with a persistent vault or secret store. MCP is optional. Use when the user pastes "set up https://scrollport.com/start" or asks for Scrollport capabilities. license: MIT --- # Scrollport — start here Scrollport supports MCP, CLI and direct API connections. **MCP is optional.** If your agent cannot register an MCP server, it can connect through authenticated HTTPS requests using device authorisation and secure credential storage, with human approval. ## Connection routes by environment Use the first applicable route. Check the direct API route before concluding that an environment is incompatible; it needs neither a shell nor MCP registration. | Environment | Connection route | | --- | --- | | Working Scrollport connection or stored credential | Reuse and verify it; do not create a duplicate. | | Persistent shell, writable user home and permission to run npx | CLI-managed device authorisation. | | Remote MCP connector with OAuth support | Remote MCP with OAuth. | | Authenticated HTTPS requests and a persistent secret store | Direct API with device authorisation. | A persistent vault, harness secret store, OS keychain or the CLI's protected credential file qualifies as secure storage. A hosted or temporary runtime can connect when its credential is retained in a persistent secret store and made available only to authorised future sessions. Do not put credentials in chat, logs, URLs or committed files. Scrollport gives AI agents access to a growing catalog of verified tools through nine control tools: `search_tools`, `inspect_tool`, `run_tool`, `get_run`, `list_apps`, `get_wallet`, `get_files`, `upload_file` and `delete_file`. One Scrollport account and pay-as-you-go wallet manage access, spending and authorisation across the catalog. Tools marked **Ready to run** include provider access, so they need no separate provider account, API key or subscription. Tools marked **Requires connected account** act inside an account the human already uses; `list_apps` reports readiness while authorisation remains separate and human-controlled. Read this document once to establish or reuse a Scrollport connection. Keep and re-read the [Scrollport skill](https://scrollport.com/skill), which explains how to choose and use tools safely. ## For humans This page helps your agent choose the safest connection method, ask for your authorisation and verify the connection. Setup does not run a paid catalog tool or charge your wallet. This page is deliberately readable by both people and agents. It contains no hidden instructions and does not ask an agent to bypass human approval. You can also start on the web: create your account at [scrollport.com/sign-up](https://scrollport.com/sign-up), then connect your agent from your dashboard. Both routes lead to the same account. During setup: - your agent may ask you to sign in with Google or with a code sent to your email; - it will separately ask you to authorise its connection; - for CLI or direct API setup, you should check that the code shown by your agent matches the approval page; - for remote MCP, you should check the connector name, requested scopes and return host before authorising; and - a scoped credential is returned directly to the CLI, harness or connector and is never displayed on the web page. If the code or connector details do not match, do not approve the request. ## For agents Read the [Scrollport skill](https://scrollport.com/skill) for product doctrine, then establish or reuse one working Scrollport connection and verify the nine control tools. Keep the human approval boundary intact throughout. The human may already have an account they created on the website. The normal approval step signs them in to it, so never ask them to create another account. If they would rather start on the web, send them to https://scrollport.com/sign-up and continue once they have signed up. ## Assess the environment deterministically Follow these steps in order. Do not ask the human to choose between CLI, API and MCP. The skill supplies tool-use doctrine; this page remains the authority for establishing the connection. 1. Check whether the nine Scrollport control tools or a working stored credential already exist. Verify them with the free `get_wallet`, `list_apps` or `search_tools` control tool and reuse them when they work. Do not mint a duplicate. 2. If shell commands are available on a persistent machine, the current OS user's home directory is writable and you have permission to run `npx`, use the CLI-managed credential route by default. 3. Otherwise, if this harness supports a remote MCP connector with OAuth, use the remote MCP route and the client-specific guide below. 4. Otherwise, if this harness can make authenticated HTTPS requests and securely retain a bearer secret in its existing credential store, use the direct device API route. A persistent vault qualifies even when the runtime has no shell or MCP support. Confirm that it can store the returned credential and inject it into future requests without exposing it. 5. Before reporting incompatibility, check all applicable routes and identify the specific missing capability: authenticated requests, persistent secret storage or a human authorisation handoff. If none works, do not mint a credential that will immediately be lost and left live. Explain what the environment needs to support; do not infer incompatibility from the client name or missing MCP registration alone. 6. Choose the tool transport separately from credential acquisition. Use remote MCP when the harness supports it; otherwise use the nine direct HTTP control-tool endpoints. 7. Verify with a free `get_wallet` or `search_tools` call, save and register the [Scrollport skill](https://scrollport.com/skill), then report the credential scope and transport without printing any secret. Use these known-client defaults to confirm the environment assessment: - claude.ai, Claude Desktop and Cowork use remote MCP because they do not expose a persistent shell for CLI setup. - Codex and Claude Code use CLI by default when they run on a persistent writable machine with shell access. Cursor, Hermes and OpenClaw follow the same environment rule. Remote MCP remains an optional transport when the client supports it. Environment facts take precedence over a product name. For example, a hosted version of a normally local harness must not be treated as though it has a writable machine. A CLI credential file is scoped to this machine and OS user, not to one agent. A direct-API credential is scoped to the harness secret store that retains it. A remote MCP authorization is scoped to one connector or connection. If the human supplied a one-time invitation, keep following the same routing order before using it. The invitation already carries the human-selected connection name and target Scrollport workspace and wallet; it does not force CLI, API or MCP and it never bypasses a required human OAuth approval. ## Standard agent permissions All new CLI, direct API and MCP connections receive the standard agent permissions: `discover`, `inspect`, `run`, `wallet`, `apps` and `files`. The `run` permission allows paid tool use subject to the workspace's spending controls; `files` includes reading, uploading and permanently deleting workspace files. This is a fixed grant, not a read-only connection. Request the full set; subsets do not produce reduced access, and `sys-admin` is never included. A free wallet check verifies the connection without exercising spending or file deletion. ## Acquire a credential ### CLI-managed credential When step 2 applies, run: ``` npx scrollport setup ``` The CLI first checks its existing credential. A working credential is reused. A missing or revoked credential starts a device request and prints `verification_uri_complete` plus the matching `user_code`. The human signs in with Google or an emailed code, returns to the still-pending request, and then separately selects `Authorise agent`. The CLI stores the returned `sp_live_…` credential at `~/.scrollport/credentials.json` with mode `0600`, inside a `0700` directory, using an atomic write. Never print or copy that credential. `npx scrollport setup --invite ` safely redeems a short-lived, single-use connection invite a human already created. The credential is still minted inside the CLI and never shown in the dashboard. ### Direct device API Use this route when the harness can make authenticated HTTPS requests and retain the returned credential in a persistent vault or other secure secret store. No shell, package installation or MCP registration is required. Creating a device request does not sign the human in and does not authorize access. ``` POST https://api.scrollport.com/v1/auth/device { "client_name": "your-harness/1.0", "access_method": "api", "scopes": ["discover","inspect","run","wallet","apps","files"] } -> { "verification_uri_complete": "...", "user_code": "HXTQ-4417", "device_code": "...", "interval": 5, "expires_in": 600 } ``` 1. Show the human both `verification_uri_complete` and `user_code` so they can match the request. 2. Poll `POST https://api.scrollport.com/v1/auth/token { "device_code": "..." }` no faster than `interval` seconds. HTTP 400 `authorization_pending` means keep waiting; `slow_down` means use the returned longer interval. Stop on `access_denied` or `expired_token`. 3. Only after the human separately authorizes the request does the next poll return `{ "api_key": "sp_live_…", "account_id": "..." }` exactly once. Put it directly into the harness's existing secret store. Never display, log, or ask the human to copy it. If a human already supplied a connection invite, redeem it directly into the same secure store: ``` POST https://api.scrollport.com/v1/auth/invite/redeem { "code": "...", "client_name": "your-harness/1.0", "method": "api" } -> { "method": "api", "api_key": "sp_live_…", "account_id": "..." } ``` ### Remote MCP OAuth Clients with remote MCP support connect to the canonical Streamable HTTP endpoint `https://mcp.scrollport.com/`. The connector opens Scrollport OAuth, where sign-in (Google or an emailed code) and `Authorise connection` are separate human actions. Scrollport issues short-lived access tokens and a stable refresh credential directly to the connector; no raw API key or token goes through the human clipboard. If the human supplied a one-time invitation, select MCP as its route before configuring the client: ``` POST https://api.scrollport.com/v1/auth/invite/redeem { "code": "...", "client_name": "the detected client", "method": "mcp" } -> { "method": "mcp", "mcp_url": "https://mcp.scrollport.com/", "account_id": "..." } ``` This records a pending setup intent only. It does not return a token or grant authority. Continue through the client's normal OAuth flow; the signed-in human explicitly binds and authorises the pending invitation on Scrollport's consent page. Identify the client and follow its guide: - For the Codex app, CLI or IDE extension, read [Codex setup](https://scrollport.com/docs/mcp/codex). - For Claude Code, read [Claude Code setup](https://scrollport.com/docs/mcp/claude-code). - For claude.ai, Claude Desktop or Cowork, read [Claude connector setup](https://scrollport.com/docs/mcp/claude). - For another client, use the [Remote MCP overview](https://scrollport.com/docs/mcp) if it supports remote Streamable HTTP with OAuth. If it cannot register that connector, assess the direct device API route above instead. When Remote MCP is selected for Claude Code, run `claude --version` before using the command-line login flow. `claude mcp login` requires Claude Code 2.1.186 or later. If the installed version is older, ask the human before running `claude update`; otherwise add the server and use the interactive `/mcp` authentication flow available in compatible older clients. Do not reject an otherwise compatible client solely because the command-line login shortcut is missing. Read the guide yourself. Give the same guide to the human only when the client requires manual configuration in its interface. Otherwise configure the client, then ask the human only to complete sign-in and select **Authorise connection**. After any MCP installation or authorization, tell the human that the connector becomes available to agents in a new session or after restarting the current harness. Do not claim the nine tools are available in the session that performed the installation unless the client demonstrably reloads MCP connections in place. ## Configure the tool transport Credential acquisition and tool transport are separate decisions. - For direct HTTP, save the [Scrollport skill](https://scrollport.com/skill) and use the nine resource routes: `GET /v1/tools/search`, `GET /v1/tools/:id`, `POST /v1/runs`, `GET /v1/runs/:id`, `GET /v1/apps`, `GET /v1/wallet`, `GET /v1/files`, `POST /v1/files/uploads` and `DELETE /v1/files/:id`. Send `Authorization: Bearer ` from the harness secret store. - For remote MCP, follow the client-specific guide above. Existing `sp_live_…` credentials remain compatible for programmatic clients, but never commit one to project configuration or ask a human to paste it into a connector UI. ## Verify and install the skill Call `get_wallet` or `search_tools` first. Both are free, so verification must not charge the wallet. For a direct API connection, make this request with the credential injected from the secret store: ```http GET https://api.scrollport.com/v1/wallet Authorization: Bearer ``` A successful response confirms authenticated access. If it fails, report the teaching error without exposing the credential and return to the relevant acquisition step; do not mint repeated credentials speculatively. Fetch [https://scrollport.com/skill](https://scrollport.com/skill), save it wherever this harness loads durable skills or tool doctrine, and register or enable it for future sessions. At the first time you use scrollport in each later session, re-fetch it, compare its `metadata.version` with the saved copy, and replace the saved copy if they differ. Report only that the fixed `discover inspect run wallet apps files` scope works and whether the selected transport is direct HTTP or remote MCP. Never print the credential, authorization code, access token or refresh token.