> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Overview

> Model Context Protocol server for AI-powered Gumnut integration

Gumnut provides a cloud-hosted MCP (Model Context Protocol) server that lets your AI assistant work with your photo library. You can use it from tools like Claude, Cursor, ChatGPT, and other MCP-compatible applications to search, organize, and manage your photos with natural language. In compatible MCP hosts, the assistant can also inspect image pixels directly instead of relying only on metadata or signed asset URLs.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open protocol that lets AI assistants securely interact with external systems. Gumnut's MCP server implements this protocol, giving your assistant authenticated, rate-limited access to your Gumnut library.

## Server URL

```text theme={null}
https://api.gumnut.ai/mcp
```

## Supported Features

The MCP server exposes Gumnut's main photo operations, including:

* **Assets**: Upload, list, update, and delete photos and videos
* **Albums**: Create and manage photo collections
* **Faces**: Review face detections, add manual face boxes for misses, and associate faces with people
* **Libraries**: Organize content across multiple libraries
* **People**: Access facial recognition and people management
* **Search**: Perform semantic and metadata-based searches
* **Map clustering**: Group geotagged assets inside a viewport so your assistant can summarize dense areas before focusing on individual photos
* **Image understanding**: Let compatible MCP hosts inspect image assets directly for tasks like reading text, describing a scene, or answering questions about visible details

If the detector misses someone, your assistant can add a manual face box, optionally attach it to a person, and come back later to review any unassigned faces.

### MCP Apps

Gumnut supports the [MCP Apps](https://apps.extensions.modelcontextprotocol.io) standard, enabling rich interactive UI experiences within MCP-compatible clients. When you use a client that supports MCP Apps, you'll get visual photo grids, album cards, and other interactive elements alongside the standard tool-based interactions.

## Let your assistant inspect photos

Gumnut's MCP server includes a native `view_asset` tool for image-aware workflows. When your MCP client supports image results from tools, the assistant can look at an image asset itself rather than only its metadata or a signed `asset_url` meant for client rendering.

This is useful when you want your assistant to:

* Read text from signs, receipts, slides, documents, or screenshots in your library
* Describe what is visible in a specific photo or image asset
* Answer questions about details such as objects, colors, or layout

Your assistant will typically search or list assets first, then inspect the specific image asset it needs. If an asset is still processing or is not available as an image result yet, the tool asks the assistant to retry later instead of returning partial visual content.

<Note>
  MCP tool calls follow the same weighted rate-limit model as the REST API. Each tool call is charged once using the comparable REST operation, so `view_asset` counts like a metadata read rather than a full file download. See [Rate Limiting](../apis/rate-limiting) for the cost classes and retry guidance.
</Note>

## Let your assistant save photos back

`view_asset` has a write-side counterpart, `save_asset`, which ingests a new image or video into a library from bytes the assistant supplies. Together they close the loop: your assistant can look at a photo, produce a new version of it, and save that version into your library.

This is what makes prompt-driven editing work through an AI assistant rather than through a Gumnut endpoint. You can ask your assistant to restyle a photo, blur the faces of everyone under 18 before you share an album, or generate a variation on a shot, and keep the result alongside the original.

A saved asset goes through the same pipeline as a normal upload — checksum deduplication, storage-cap enforcement, and the usual embedding, face-detection, and description processing — so it is searchable like anything else you upload.

<Note>
  `save_asset` takes the bytes directly and never downloads from a URL, so the assistant must have the image data itself. It is practical for images and short clips; use the [REST API](../apis/overview) or an [SDK](../sdks/overview) to upload large videos.
</Note>

## Location-aware clustering

The MCP server also exposes `get_geo_clusters` for map-style browsing. Use it when you want your assistant to summarize geotagged assets inside a viewport before you ask it to focus on individual photos. Pass `bbox` as `min_longitude,min_latitude,max_longitude,max_latitude`, then choose `cell_size` in decimal degrees for the clustering granularity. Each cluster includes a centroid, an asset count, and a `representative_asset_id` you can use as a cover image or lookup key.

Use `get_geo_clusters` when you want counts and map groupings, then switch to `list_assets` when you want the individual assets inside one area. For the HTTP version and its filtering behavior, see [Pagination & Filtering](../apis/pagination-and-filtering#map-views-with-geo-clusters).

## Authentication

The MCP server supports multiple authentication methods:

* **API Keys**: For CLI tools and server applications — `Bearer apikey_...`
* **OAuth 2.1**: For browser-based tools and web applications — `Bearer oat_...`
* **Session Tokens**: Automatic session management through cookies

See [Authentication](../authentication/overview) for details on each method.

## Example Interactions

Once configured, you can interact with Gumnut through natural language in your AI assistant:

**Basic Operations**:

```text theme={null}
"List all my photo albums"
"Upload this image to my library"
"Create a new album called 'Summer 2024'"
"Find all photos taken in December"
```

**Advanced Queries**:

```text theme={null}
"Show me photos with detected faces"
"Find all images similar to this one"
"Get photos taken with an iPhone 15 Pro"
"List assets that haven't been processed yet"
```

**Image-Aware Prompts**:

```text theme={null}
"Find the photo of the whiteboard from this week and summarize what's written on it"
"Read the text on the menu photo from last night"
"Look at my latest receipt photo and tell me the total amount"
```

**Bulk Operations**:

```text theme={null}
"Add all beach photos to a new album"
"Delete all duplicate images"
"Organize photos by date into monthly albums"
"Tag all photos with detected people"
```

## Getting Started

See the [MCP Setup guide](./setup) for step-by-step instructions to configure the MCP server in:

* [Claude Code](./setup#claude-code)
* [Cursor](./setup#cursor)
* [Claude Web (claude.ai)](./setup#claude-web-claudeai)
* [ChatGPT](./setup#chatgpt)

Those aren't the only clients that work — any client that supports remote MCP servers and can authenticate to them, through either OAuth sign-in or a configurable `Authorization` header, can connect. See [Any MCP client](./setup#any-mcp-client) for the URL and authentication options, and [Local and self-hosted models](./setup#local-and-self-hosted-models) if you're running the model on your own hardware.

## Troubleshooting

Having issues? See the [MCP Troubleshooting guide](./troubleshooting) for common problems and solutions.