Skip to main content

​
MCP Server Overview

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

​
Prerequisites

  1. A Gumnut account
  2. An API key (get one from the dashboard)
  3. An MCP-compatible tool (Claude, Cursor, etc.)

​
Configuration

Each tool has its own configuration method. Here’s the general format: 
{
  "gumnut": {
    "url": "https://mcp.gumnut.ai/mcp",
    "transport": "http",
    "headers": {
      "Authorization": "Bearer apikey_YOUR_API_KEY"
    }
  }
}
See tool-specific guides:

​
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

​
Development & Testing

​
Testing with Inspector

Test the MCP server using the MCP Inspector: 
npx @modelcontextprotocol/inspector@latest
Configure the inspector to connect to https://mcp.gumnut.ai with your API key.

​
Troubleshooting

​
Connection Issues

Problem: MCP client can’t connect
  • Verify the server URL is exactly https://mcp.gumnut.ai/mcp
  • Check your internet connection
  • Ensure your API key is valid
  • Try the health endpoint: curl https://mcp.gumnut.ai/health

​
Authentication Errors

Problem: 401 Unauthorized responses
  • Verify API key format: Bearer apikey_...
  • Check key hasn’t been revoked
  • Ensure proper Authorization header
  • Try regenerating your API key

​
Rate Limiting

Problem: 429 Too Many Requests
  • Check the retry-after header
  • Implement exponential backoff
  • Consider request batching
  • Monitor your usage in the dashboard

​
CORS Issues

Problem: Browser-based client CORS errors
  • Ensure using HTTPS
  • Check browser console for details
  • Verify client sends proper headers
  • Contact support if persists

​
Support

Need help with the MCP server? The Gumnut MCP server brings the power of AI to your photo management workflow. Start using it today to automate and enhance your photo library!
⌘I