# Connect an AI client to SnapScout

SnapScout exposes `search_image_sources` over MCP. From your AI client, give the tool a public image URL or a base64-encoded JPEG, PNG or WebP. The first page contains up to ten distinct matches with source links, similarity scores and available image previews. Use **Load more**, or ask for the next page, to see ten more from the same search. SnapScout keeps up to 80 distinct results available to your account for 30 minutes.

SnapScout sends available previews as images the model can inspect. ChatGPT uses its own web search to check source pages and publicly indexed LinkedIn profiles for supporting details. The gallery displays the matches. ChatGPT summarizes independently sourced findings in a cited paragraph. Its record_source_research call saves actual web queries, source URLs, findings and candidate image links alongside the original result links in the calling account. Portrait comparisons are pending a future FaceDB integration. A similarity score measures visual similarity.

## Add SnapScout to ChatGPT

1. Open [ChatGPT Plugins](https://chatgpt.com/plugins). Select **+**, then **Add custom MCP server**.
2. Enter **SnapScout** as the name and paste `https://snapscout.ai/mcp` in the connection field.
3. Choose **OAuth or no authentication**. If advanced settings ask how to configure the client, choose **Client ID Metadata Document (CIMD)**. Review the permissions and select **Create as a plugin**.
4. In a new chat, select **@SnapScout**, attach your photo, and ask for its source pages. When prompted, connect your own SnapScout account, approve access, and return to the chat.

Availability of custom servers depends on your ChatGPT account and workspace settings. You can revoke the connection from [your SnapScout account](https://snapscout.ai/account).

## Get a personal key

Open [your SnapScout account](https://snapscout.ai/account), sign in with Google and create a named key. Copy it into the secret settings of your MCP client. You can revoke a key in the same account. Personal keys share a limit of 10 searches per minute per account.

## Server settings for administrators

In Punica, open Settings → Keys. Configure `FACEDB_API_URL` and `FACEDB_API_TOKEN` for the index, then set `SNAPSCOUT_MCP_TOKEN` to a separate, randomly generated secret. The service reads these values on the server. An existing installation can continue using its previously configured MCP token.

Use an HTTPS address reachable by your AI client. The bearer token protects `/mcp`, where all image searches run. The website provides the endpoint and connection instructions.

## Remote MCP clients

Choose Streamable HTTP in the client's MCP connection settings. Use your SnapScout app's origin followed by `/mcp`, for example `https://snapscout.ai/mcp`. Configure bearer authentication with your personal key. For clients with custom headers, set `Authorization` to `Bearer YOUR_TOKEN`. Store this value in the client's secret settings.

## Desktop clients using stdio

Download [the stdio adapter](./snapscout-mcp.mjs) from the same SnapScout app, or use `public/snapscout-mcp.mjs` from the project. Run it with Node.js 20 or later. It forwards MCP messages to your SnapScout endpoint. For clients using an `mcpServers` configuration, replace the example URL, path and token in this entry. Use the client's environment secret store where available.

```json
{
  "mcpServers": {
    "snapscout": {
      "command": "node",
      "args": ["/absolute/path/to/snapscout-mcp.mjs"],
      "env": {
        "SNAPSCOUT_MCP_URL": "https://snapscout.ai/mcp",
        "SNAPSCOUT_MCP_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

## Check the connection

After connecting, open the client's tool list and look for `search_image_sources`. Ask the AI to search for source pages for an image you supply and cite the returned URLs. The tool takes exactly one argument, either `image_url` or `image_base64`. Both inputs have a 16 MiB decoded image limit. An empty results list is a successful search with no source trail.

You can also check discovery without sending an image. With the endpoint and token set in your shell environment, run

```sh
curl --silent --show-error "$SNAPSCOUT_MCP_URL" \
  -H "Authorization: Bearer $SNAPSCOUT_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A successful response lists the tool. HTTP 401 means the client token is missing or incorrect. HTTP 503 indicates a temporarily unavailable account service. A FaceDB configuration or search failure appears in the tool call result with `isError: true`.
