SWSH Public API · MCP

SWSH MCP

The SWSH MCP server lets AI assistants such as Claude and ChatGPT work with your SWSH albums on your behalf. Once connected, an assistant can search your albums, answer questions about the photos in them, label photos in bulk, and package photos up for download — all through a small set of approved tools and only with the permissions you grant.

The server implements the Model Context Protocol over Streamable HTTP and uses OAuth 2.1 for sign-in. There is nothing to install and no API key to manage: you connect from inside your assistant and approve access with your SWSH account.

Server URL: https://mcp.joinswsh.com/mcp

Before you start

You need a SWSH account. If you don't have one yet, sign up on the web.
Sign-in happens in your browser. You'll be asked to log in to SWSH (if you aren't already) and then to approve the permissions the assistant requests.
The assistant acts as you: it can only see and change albums you already have access to, and album edits are limited to albums you administer.

Set up in Claude

Custom connectors are available in Claude on the web and in the Claude desktop apps. At the time of writing, adding a custom connector requires a paid Claude plan — check Claude's connector documentation for current availability.

Open Settings → Connectors in Claude.
Choose Add custom connector.
Enter a name (for example SWSH) and paste the server URL:
```
https://mcp.joinswsh.com/mcp
```
Click Add, then Connect. A SWSH sign-in window opens.
Log in to SWSH if prompted, review the requested permissions, and click Allow.

You'll be sent back to Claude with the connector enabled. In a new conversation, make sure the SWSH connector is toggled on in the tools menu, then ask Claude something like "Which of my albums has the most photos?"

Claude Code

From a terminal, add the server and authenticate:

claude mcp add --transport http swsh https://mcp.joinswsh.com/mcp

Then run /mcp inside Claude Code and follow the prompt to sign in. Claude Code uses a localhost callback for OAuth, which the SWSH authorization server accepts.

Set up in ChatGPT

ChatGPT connects to remote MCP servers through connectors (sometimes labelled Apps). Creating a custom connector currently requires enabling Developer mode; availability varies by plan and workspace — see OpenAI's connector documentation for details.

Open Settings → Apps & Connectors (or Connectors) in ChatGPT.
Under Advanced settings, turn on Developer mode.
Back on the connectors page, choose Create.
Enter a name (for example SWSH) and the MCP server URL:
```
https://mcp.joinswsh.com/mcp
```
Set Authentication to OAuth and create the connector.
Click Connect, log in to SWSH if prompted, review the requested permissions, and click Allow.

To use it, start a new chat, open the + menu, and enable the SWSH connector for that conversation.

Other MCP clients

Any client that supports MCP over Streamable HTTP with OAuth 2.1 can connect. The authorization server supports:

Authorization code flow with PKCE (S256), including refresh tokens via the offline_access scope.
Dynamic client registration and client ID metadata documents.
Loopback (http://localhost / http://127.0.0.1) redirect URIs for desktop and CLI clients, with any port.

Registration is limited to redirect URIs on an allowlist of well-known assistant domains plus loopback addresses. If your client uses a hosted callback on another domain, contact us.

Endpoint	URL
MCP server	`https://mcp.joinswsh.com/mcp`
Protected resource metadata	`https://mcp.joinswsh.com/.well-known/oauth-protected-resource/mcp`
Authorization server	`https://oauth.joinswsh.com`
Authorization server metadata	`https://oauth.joinswsh.com/.well-known/oauth-authorization-server`

Permissions

When you connect, the consent screen lists exactly what the assistant is asking for. The permissions available to every account are:

Scope	What it allows
`user:read`	Read your name and user ID
`album:read`	Search and list the albums you administer
`photo:read`	Read photo records, build snapshots, and export or download photos
`photo:write`	Add and remove labels on photos

Tools whose permission you did not grant are not offered to the assistant at all. If a client requests no specific scopes, only user:read is granted.

What the assistant can do

Tool	Description
`get_current_user`	Confirm which SWSH account is connected
`search_album`	Find albums you administer by name, with share links and photo counts
`create_snapshot_from_album`	Capture an album's photo records into a queryable snapshot
`filter_snapshot` / `map_snapshot`	Narrow a snapshot or project a single field (uploaders, labels, timestamps) — server-side, no download needed
`get_snapshot`	Re-open a snapshot created earlier
`export_snapshot`	Export a snapshot as JSON or CSV
`bulk_label_snapshot_photos`	Add or remove a label on every photo in a snapshot
`download_photos`	Zip the photos in a snapshot and email a download link to your verified address
`get_job_status`	Check on a long-running download or export

Snapshots are the core idea: instead of downloading photos, the assistant asks the server to filter and summarize an album's records, so "how many photos did Alex upload after 9pm?" is answered without any photo leaving SWSH.

Security and revoking access

Access tokens are short-lived (one hour) and refresh tokens expire after 30 days of non-use. Clients renew them automatically while the connector stays enabled.
To revoke access, remove or disconnect the SWSH connector in your assistant's settings. The client revokes its tokens, and any that remain expire on their own.
Requests are rate limited per account. If the assistant reports a rate-limit error, wait a moment and try again.
Only sign in through the https://oauth.joinswsh.com consent page, and check that the redirect destination shown on that page matches the assistant you're connecting.

Feedback

Questions, bugs, or a tool you wish existed? Contact us or email support@joinswsh.com.