Getting Started Dashboard Personas Locations Scenes Predictions Collections Explore Gallery Prompt Style Library User Profiles Settings MCP Server

MCP Server

The Fellowship Image Maker MCP (Model Context Protocol) server enables AI clients — such as Claude Desktop, Claude Code, or Cursor — to interact with your personas, locations, scenes, and generate image prompts directly without opening the web interface.

Overview

MCP is a standardized protocol that lets AI assistants call tools on your application. The Fellowship MCP server exposes 21 tools organized into four categories:

  • Personas — list, view, create, update, delete
  • Locations — list, view, create, update, delete
  • Scenes — list, view, create, update, delete, attach/detach personas and locations
  • Prompts — generate image prompts for scenes, view prediction history

Authentication

All MCP requests require an API token issued from the Settings > API Keys page.

Generating an API Token

  1. Log in to Fellowship Image Maker.
  2. Go to Settings → API Keys.
  3. Click Create Token.
  4. Optionally name it (e.g., "Claude Desktop", "Cursor").
  5. Copy the token value (shown once; save it securely).
  6. Use the token in your MCP client configuration.

Revoking Tokens

Tokens can be revoked at any time from the API Keys page. Once revoked, they cannot be reused.

Configuring MCP Clients

Claude Desktop

Add the server to ~/.mcp/mcp.json:

{
  "mcpServers": {
    "fellowship": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Replace your-domain.com and YOUR_API_TOKEN with your deployment URL and generated token. Restart Claude Desktop for changes to take effect.

Claude Code

The same configuration in .mcp.json works for Claude Code. Ensure you also enable the server in Claude Code's settings.

Available Tools

Personas

Tool Description
list-personas List your personas, paginated 15 per page.
get-persona Fetch a persona by slug (name, description, category).
create-persona Create a persona (name, category, description, notes).
update-persona Update persona fields by slug.
delete-persona Delete a persona by slug.

Categories: character or object

Locations

Tool Description
list-locations List your locations, paginated 15 per page.
get-location Fetch a location by slug (name, description, epoch, atmospheres).
create-location Create a location (name, description, epoch, notes).
update-location Update location fields by slug.
delete-location Delete a location by slug.

Scenes

Tool Description
list-scenes List your scenes with persona/location counts.
get-scene Fetch scene details including attached personas and locations.
create-scene Create a scene (name, description with #p:slug / #l:slug syntax).
update-scene Update scene fields by slug.
delete-scene Delete a scene by slug.
attach-persona-to-scene Link a persona to a scene.
detach-persona-from-scene Unlink a persona from a scene.
attach-location-to-scene Link a location to a scene.
detach-location-from-scene Unlink a location from a scene.

Scene Description Syntax:

  • Reference personas with #p:slug (e.g., "A #p:old-knight stands in #l:castle-tower")
  • Reference locations with #l:slug
  • The AI will resolve these references when generating prompts

Prompts

Tool Description
generate-prompt Generate an image prompt for a scene by slug. Returns a prediction ID and the generated prompt text.
list-predictions List all predictions (generated prompts) for a scene, newest first.

Example Workflow

Using Claude Desktop with the MCP server enabled:

  1. Create a persona:

    Use the "create-persona" tool:
- Name: "The Alchemist"
- Category: "character"
- Description: "A mysterious figure in tattered robes, eyes glowing with arcane knowledge..."

  2. Create a location:

    Use the "create-location" tool:
- Name: "Tower Laboratory"
- Description: "A spiraling tower filled with bubbling alchemical apparatus..."

  3. Create a scene:

    Use the "create-scene" tool:
- Name: "Alchemical Experiment"
- Description: "#p:the-alchemist conducting a dangerous ritual in #l:tower-laboratory"

  4. Attach the persona and location:

    Use "attach-persona-to-scene":
- Scene slug: "alchemical-experiment"
- Persona slug: "the-alchemist"

Use "attach-location-to-scene":
- Scene slug: "alchemical-experiment"
- Location slug: "tower-laboratory"

  5. Generate a prompt:

    Use the "generate-prompt" tool:
- Scene slug: "alchemical-experiment"

    The AI resolves all #p: and #l: references and returns a detailed image prompt.

Authorization

All tools respect your existing authorization policies:

  • You can only list/view/edit your own personas, locations, and scenes
  • Public personas, locations, and scenes are readable by all users
  • Each tool returns an error if you lack permission

Error Handling

If a tool call fails:

  • 401 Unauthorized — Your token is invalid, revoked, or has expired
  • 403 Forbidden — You lack permission to access the resource
  • 404 Not Found — The persona/location/scene does not exist
  • 422 Unprocessable Entity — Validation error (e.g., duplicate slug, missing required fields)

Rate Limiting

MCP requests are rate-limited to 60 requests per minute per user.

Troubleshooting

Tools not appearing in Claude Desktop/Code:

  • Verify the token is correct and not revoked
  • Check that the URL is reachable and returns HTTP 200
  • Ensure "type": "http" is set in the configuration
  • Restart the client application

"Unauthorized" errors:

  • Generate a new token from Settings > API Keys
  • Ensure the entire token string (no extra spaces) is in the header

Slug conflicts:

  • Slugs must be unique within your account
  • If a slug is already taken, use update-{type} to modify the existing item or use a different name
← Settings