Skip to main content
Gumnut provides a cloud-hosted MCP (Model Context Protocol) server that enables AI assistants to interact with the Gumnut API. This allows tools like Claude, Cursor, and other MCP-compatible applications to access and manipulate your photo library programmatically.

​
What is MCP?

The Model Context Protocol is an open protocol that enables AI assistants to securely interact with external systems. Gumnut’s MCP server implements this protocol, providing:
  • Full access to all Gumnut API operations
  • Authenticated access using your credentials
  • Structured responses optimized for AI understanding
  • Built-in safety features and rate limiting

​
Features

​
Complete API Coverage

The MCP server provides access to all Gumnut API operations:
  • Assets: Upload, list, update, and delete photos/videos
  • Albums: Create and manage photo collections
  • Faces: Manage detected faces and associate them with people
  • Libraries: Organize content across multiple libraries
  • People: Access facial recognition and people management
  • Search: Perform semantic and metadata-based searches

​
Dual Authentication Support

The server supports multiple authentication methods:

​
Session Tokens & OAuth (via Clerk)

For browser-based tools and web applications:
  • Automatic session management through cookies
  • OAuth 2.1 compliant flow with PKCE support
  • Bearer token format: Bearer oat_*

​
API Keys

For CLI tools and server applications:
  • Direct API key authentication
  • Bearer token format: Bearer apikey_*

​
HTTP Endpoints

The MCP server exposes standard HTTP endpoints following the MCP specification:
  • POST / - Main MCP protocol endpoint
  • GET /health - Health check endpoint
  • GET /.well-known/oauth-protected-resource/mcp - OAuth metadata
  • GET /.well-known/oauth-authorization-server - Authorization server metadata

​
CORS Support

Full CORS support enables browser-based MCP clients to connect directly to the server.

​
Server URL

The Gumnut MCP server is available at: 
https://mcp.gumnut.ai/mcp

​
Setting Up MCP

For detailed setup instructions for your specific tool, see the MCP Setup guide:

​
Using the MCP Server

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

​
Example Interactions

Basic Operations: 
"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: 
"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"
Bulk Operations: 
"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"

​
MCP Protocol Details

​
Request Format

The server accepts standard MCP protocol requests: 
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": "1"
}

​
Response Format

Responses follow the MCP specification: 
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "list_assets",
        "description": "List all assets in your library",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": { "type": "number" },
            "offset": { "type": "number" }
          }
        }
      }
    ]
  },
  "id": "1"
}

​
Available Tools

The MCP server exposes Gumnut operations as tools:
  • list_assets - Get assets with filtering
  • upload_asset - Upload new photos/videos
  • create_album - Create photo albums
  • add_to_album - Add assets to albums
  • search_assets - Search with natural language
  • get_people - List detected people
  • get_tasks - Monitor processing status
  • And many more…

​
Security

​
Authentication Security

  • API keys are transmitted over HTTPS only
  • OAuth tokens include scope limitations
  • Session tokens are HTTP-only cookies
  • All credentials are validated on each request

​
Rate Limiting

The MCP server enforces rate limits:
  • Inherits API rate limits (1000 req/hour)
  • Additional MCP-specific limits may apply
  • Clear error messages for rate limit violations

​
Data Privacy

  • The MCP server doesn’t store request/response data
  • All operations are logged for security auditing
  • Credentials are never logged or stored
  • TLS encryption for all connections

​
OAuth 2.1 Compliance

The server implements full OAuth 2.1 compliance:

​
WWW-Authenticate Headers

Failed authentication returns proper challenge headers: 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Gumnut MCP", scope="read write"

​
Token Protection

  • Rejects tokens in query parameters
  • Enforces HTTPS for all token transmission
  • Supports PKCE for public clients

​
Metadata Endpoints

RFC 8414 compliant metadata available at well-known URLs:
  • Protected resource metadata
  • Authorization server configuration
  • Supported grants and scopes

​
Troubleshooting & Support

Having issues? See the MCP Troubleshooting guide for common problems and solutions. For additional help: