# Photonfolio MCP Capabilities

Photonfolio MCP is the remote connected-assistant surface for approved Photonfolio workspace context.

## Connection

- MCP URL: https://mcp.photonfolio.com/mcp
- Transport: streamable HTTP
- Authentication: OAuth 2.0 with PKCE and bearer tokens
- Authorization server: https://api.photonfolio.com/api/v1/photonfolio/mcp/oauth
- Server card: https://photonfolio.com/.well-known/mcp/server-card.json
- Human setup page: https://photonfolio.com/mcp

## Available Today

- Read the authenticated workspace summary.
- Read album and gallery delivery context.
- Read photo library context, including optional text, album, and project filters.
- Search workspace, album, and photo context.
- Read project and workflow status.
- Read billing and plan status.
- Generate response-only workflow recommendations from current context and a stated goal.
- Read JSON resources for workspace, workflow, and billing context.

## Current OAuth Scopes

- `workspace.read`
- `albums.read`
- `photos.read`
- `search.read`
- `workflow.read`
- `billing.read`
- `drafts.generate`

## Tools

### photonfolio_workspace_context

- Title: Workspace context
- Purpose: Read the authenticated Photonfolio workspace summary.
- Required scopes: `workspace.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

### photonfolio_albums

- Title: Albums
- Purpose: Read album and gallery delivery context for the workspace.
- Required scopes: `albums.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Album results page."
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Albums per page."
    }
  },
  "additionalProperties": false
}
```

### photonfolio_photos

- Title: Photos
- Purpose: Read photo library context for the workspace.
- Required scopes: `photos.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Photo results page."
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Photos per page."
    },
    "q": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional photo search terms."
    },
    "album": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional album slug."
    },
    "project": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional project slug."
    }
  },
  "additionalProperties": false
}
```

### photonfolio_search

- Title: Search
- Purpose: Search workspace, album, and photo context.
- Required scopes: `search.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Search terms."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

### photonfolio_workflow_state

- Title: Workflow state
- Purpose: Read project and workflow status for the workspace.
- Required scopes: `workflow.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

### photonfolio_billing_context

- Title: Billing context
- Purpose: Read billing and plan status for the workspace.
- Required scopes: `billing.read`
- Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

### photonfolio_draft_workflow_recommendations

- Title: Draft workflow recommendations
- Purpose: Create response-only workflow recommendations from current context.
- Required scopes: `workspace.read`, `workflow.read`, `drafts.generate`
- Input schema:

```json
{
  "type": "object",
  "properties": {
    "goal": {
      "type": "string",
      "minLength": 1,
      "maxLength": 400,
      "description": "Workflow outcome to draft toward."
    },
    "project_id": {
      "type": "string",
      "maxLength": 80,
      "description": "Optional project identifier."
    }
  },
  "required": [
    "goal"
  ],
  "additionalProperties": false
}
```

## Resources

### photonfolio_workspace

- URI: `photonfolio://workspace/context`
- Title: Workspace context
- Purpose: Current workspace summary for the linked Photonfolio account.
- MIME type: `application/json`
- Required scopes: `workspace.read`

### photonfolio_workflow

- URI: `photonfolio://workspace/workflow`
- Title: Workflow state
- Purpose: Current project and workflow state for the linked Photonfolio account.
- MIME type: `application/json`
- Required scopes: `workflow.read`

### photonfolio_billing

- URI: `photonfolio://workspace/billing`
- Title: Billing context
- Purpose: Current billing and plan context for the linked Photonfolio account.
- MIME type: `application/json`
- Required scopes: `billing.read`

## Boundaries

- Current MCP capabilities are read access plus response-only draft recommendations.
- MCP does not upload photos, edit images, publish galleries, change galleries, send client messages, change billing, change account settings, delete data, or write backlog records.
- Use OAuth scopes to request only the access areas needed for the user's task.
- Browser-session Photonfolio settings routes are not public agent APIs.
- No MCP prompts are advertised today.

## Maintenance Note For Agents

When Photonfolio MCP adds or removes tools, resources, scopes, prompts, or permission boundaries, update /mcp.md, /mcp, /llms.txt, /auth.md, and /.well-known/mcp/server-card.json in the same change.