Integrations
Surface your external tools — Jira, GitHub, Slack, Notion, Linear, ServiceNow, Bugsnag, Datadog, and any custom source — as a grouped, filterable tree in the project sidebar. Connect once, reuse everywhere.
Integrations surface items from your external tools — issues, pull requests, mentions, pages, errors, monitors — as a grouped, filterable tree in the project sidebar. They keep your outside work visible next to your sessions, and any item can be opened, copied, or handed straight to an agent.
Scape ships connectors for the common tools, but the real power is that an integration is just a JSON config. You can add your own source — any HTTP API that returns a list — without writing a line of Swift. See Custom integrations for the config format end to end.
The model: connections and profiles
Two ideas keep integrations reusable across your projects:
- A connection is a credential you enter once, and it's global — shared across every project and every Mac. A connection owns the settings (a Jira domain, a ServiceNow instance) and the secret (an API token, a username/password). Its metadata syncs across your devices; the secret itself never leaves the device it was entered on — it lives in the macOS Keychain, never in the database, never on the sync record.
- A profile is a per-project view backed by a connection. Each profile has its own name, its own grouping (how the tree nests), and its own row template (how each leaf renders). Add the same connection to three projects and you get three independent profiles that share one credential.
Because the secret is device-local, a connection you created on one Mac shows as Not connected on another until you Connect on this device — a deliberate per-device consent step, not a bug.
Adding an integration
Right-click a project in the sidebar and choose + Add Integration (or use the Add Integration row under the project). This opens the integration library — a modal with:
- A list of connectors — the bundled vendors show their brand tile; a config you've saved yourself should use a neutral glyph.
- Custom… — paste or import your own config (see Custom integrations).
- Connections — manage your global connections: connect a new one, connect an existing one on this device, or edit one.
Pick a connector, fill in its settings and credential, and add it to the current project. The form shows exactly which hosts the credential will be sent to before you save it — the credential is never sent anywhere else. Reuse a connection you've already made, or create a new one inline.
Connect on this device
A connection's credential is stored in the Keychain on the machine where you entered it. On any other Mac the profile appears but shows Not connected. Open + Add Integration → Connections, find the connection, and choose Connect on this device… to enter the credential locally. The same thing happens if the connection's hosts or secret names change — Scape asks you to review and re-confirm before it will poll again.
Editing a connection or profile
- Edit a connection from the Connections pane to change its settings or credential. Because a settings change can move which hosts the credential is sent to, the form shows you the newly rendered hosts — the same informed-consent moment as first entering the credential.
- Edit a profile with Edit… on the profile's row. This opens the same focused modal where you can rename it, change its grouping, or re-attach it to a different connection.
Bundled connectors
| Connector | What it shows | Credential |
|---|---|---|
| Jira | Issues by JQL — defaults to your unresolved issues | Site domain + email + API token |
| GitHub Pull Requests | Open PRs across the project's repositories | Personal access token |
| GitHub Issues | Issues by search qualifiers — defaults to those assigned to you | Personal access token |
| Slack Mentions | Mentions of you across your workspace | User token + your Slack user id |
| Notion | Pages shared with your Notion integration | Internal integration token |
| Linear | Issues assigned to you | Personal API key |
| ServiceNow | Records across one or more tables (incidents, changes, problems…) | Instance + username/password or API key |
| Bugsnag | Open errors across your org's projects | Auth token + org id/slug |
| Datadog | Monitors, grouped by team / env / service tags | API key + application key + site |
Each connector declares its own settings and auth style; the form only asks for what that connector needs. GitHub Pull Requests, for example, fans out over the repositories already in your project, so it has no settings to fill in — just the token.
The tree
Every profile opens as a grouped tree:
- Group by any field the connector exposes — repository, assignee, status, label, channel, team, table, priority… The chips at the top of the tree control the nesting, and you can stack several to nest one level inside another. Your grouping choice syncs across your Macs.
- Query — connectors with an editable query (Jira JQL, GitHub search qualifiers, a ServiceNow encoded query, Datadog monitor tags) show a query field, often with presets.
- Filter — the filter bar narrows the visible tree; ⌘K focuses it.
- Hide items you don't care about from the context menu; hidden items stay hidden on every device.
Click any item to open it in Scape's browser companion. The context menu offers Copy link, Open in active session, Start new session, and Start in new worktree (when the project has a matching repository) — which connectors offer which actions is set by the config.
Row templates
Beyond grouping, you can change how each leaf row renders — an ordered set of components (text, labels, icons) pulled from the item's fields, with per-value maps for the icon, label text, and color. Open the row-template editor from the palette icon on the grouping chips row. It shows a live sample row and a per-value mapping table so you see exactly what the tree will draw. Like grouping, a profile's row template syncs across your Macs. Custom configs decide which fields are available to a row template (see Custom integrations).
Refresh & polling
Scape polls each profile in the background (every 5 minutes by default) and caches the results locally, so the tree renders instantly on launch. The refresh button in the header fetches on demand. Fetches are rate-limited and bounded — a poll stops at the connector's item cap so a huge result set can't run away.
Security
Every request an integration makes is checked against an allowed-hosts list declared by its config — HTTPS only, default port, no embedded credentials, and the final host must match exactly. This runs on every request, including pagination follow-ups. Resolved secret values are scrubbed from anything cached or synced. Credentials live only in the macOS Keychain on the device where you entered them.
Agents
Sessions can read and manage integrations through Scape's MCP tools — an agent sees exactly what the tree shows:
| Tool | Purpose |
|---|---|
list_integrations | List the project's integrations (profiles + legacy inboxes) |
list_integration_view_items | Read the grouped items from the cache |
list_integration_view_configs | List available configs (bundled + saved) with their settings specs |
list_integration_connections | List global connections (secret names only, never values) |
get_integration_health / diagnose_integration | Last-poll status and error evidence |
refresh_integration | Trigger an on-demand poll |
set_integration_view_prefs | Change a profile's grouping, query, hidden items, or row template |
add_integration_profile | Add a profile to a project using an existing connection |
add_integration_view_item | Add a bundled connector as an unconnected profile |
open_add_integration / open_integration_settings | Open the library or a connection's settings for the user |
validate_integration_view_config / save_integration_view_config | Validate and save a custom config (saved unapproved — see below) |
An agent can author and validate configs and stage integrations for you, but there is a hard boundary: an agent can never enter a credential, approve a config that uses your stored secrets, or create/edit/delete a global connection. Those are always your action, on your device. See Custom integrations → the approval boundary.
The legacy per-tool tools (list_jira_issues, list_github_prs, list_slack_messages, and friends) still work and read the same cache.