Connector URLs
Add Martini to Claude or any MCP-compatible client using the full connector URL:
Martini also provides a core connector profile for clients or software directories that need the common project, board, upload, review, and organization tools without direct generation:
The connector supports OAuth 2.0 — when you add it, your client will redirect you to sign in with your Martini account. Existing Martini users keep access to all of their projects.
Martini’s official MCP Registry name is film.martini/mcp for clients and marketplaces that use registry metadata.
Add to Claude
- Open Claude on the web or in the desktop app.
- Go to Settings → Connectors and click Add custom connector.
- Paste
https://www.martini.film/mcpas the server URL and continue. - Sign in to Martini when prompted. If you do not already have an account, create one — the connector cannot create accounts on its own.
- Once connected, ask Claude to use Martini in any conversation. Try “list my Martini projects” or “create a new scene called Opening”to verify it’s working.
Add to Gemini CLI
- Install Gemini CLI if you do not already have it.
- Install Martini’s Gemini CLI extension from GitHub:gemini extensions install https://github.com/martini-film/mcp --auto-update
- Restart Gemini CLI.
- Run
/mcp. You should see amartiniMCP server. - If Gemini asks you to authenticate, run
/mcp auth martiniand sign in with your Martini account in the browser.
The extension points Gemini CLI at https://www.martini.film/mcp and adds Martini-specific guidance and commands for project, upload, and generation workflows.
What you can do
The connector exposes tools grouped into a few jobs to-be-done:
- Browse projects. List your projects, scenes, subjects, and assets, and pull detailed metadata when you need it.
- Organize the canvas. Create scenes, create reusable subjects (characters, props, animals), and add or move nodes on the canvas.
- Upload images. Send up to 50 images at a time directly into a scene. Audio and video uploads still happen in the Martini app for now.
- Run approved generation. In the full connector, Claude can generate media for existing or newly planned shot nodes after you approve the model, prompt, count, and estimated olive cost.
Connector profiles
Full profile
https://www.martini.film/mcp exposes the complete Martini MCP tool surface, including approved image and video generation inside Martini projects.
Core profile
https://www.martini.film/mcp-core exposes the common project, board, scene, subject, collection, upload, download, review, and organization tools. It omits direct generation tools for clients or directories that require a narrower connector surface.
Tool inventory
Every tool is documented in the connector’s metadata, including read-only versus write annotations so your client can show clear consent prompts. The inventory below describes the full profile; the core profile omits direct generation tools such as generate, create_node_and_generate, and create_nodes_and_generate.
| Tool | Description | Type |
|---|---|---|
List Projects get_projects | Search projects with optional query limits. | Read |
Get Board Overview get_board_overview | One-call orientation with scenes, subjects, collections, and canvas children. | Read |
List Board Assets get_board_assets | Summarized assets and canvas positions for a project. | Read |
Get Asset Detail get_asset | Full metadata for a single asset. | Read |
Get Asset Draft Settings get_asset_draft_settings | Generation configuration for one asset. | Read |
List Board Scenes get_board_scenes | Scenes, canvas bins, and text annotations. | Read |
List Board Subjects get_board_subjects | All subjects on a project. | Read |
Get Subject Detail get_subject | Full detail for a subject. | Read |
Get Canvas Children get_canvas_children | Direct scene or bin children; collection cards stay spatial. | Read |
Get Subject Collection get_subject_collection | One collection with hydrated member subjects. | Read |
List Subject Collections get_subject_collections | Collections with member subject names and IDs. | Read |
View Collection Card view_subject_collection_card | Compact visual card, structured metadata, and readable card resource. | Read |
Create Subject create_subject | Create a reusable character, prop, or animal subject. | Write |
Create Subject Collection create_subject_collection | Group existing subjects into a collection. | Write |
Rename Subject Collection rename_subject_collection | Rename a subject collection. | Write |
Reorder Subjects in Collection reorder_subjects_in_collection | Reorder existing subjects without changing membership. | Write |
Add Subjects to Collection add_subjects_to_collection | Add existing subjects to a collection. | Write |
Remove Subjects from Collection remove_subjects_from_collection | Remove subjects; empty collections dissolve. | Write |
Reorder Variation Stack Members reorder_variation_stack_members | Reorder existing stack members without changing membership. | Write |
Get Scene get_scene | A single scene with summaries and positions. | Read |
Create Scene create_scene | Create a new scene in a project. | Write |
Create Node create_node | Create an empty asset-backed node. | Write |
Create Node and Generate create_node_and_generate | Create a planned shot node and run an approved generation for it. | Write |
Create Nodes and Generate (Batch) create_nodes_and_generate | Create multiple planned shot nodes and run approved generations for them. | Write |
Create Nodes (Batch) create_nodes | Create multiple empty nodes. | Write |
Move Node move_node | Reposition a node on the canvas. | Write |
Check Storage Reachability check_storage_reachability | Preflight check that R2 storage is reachable for both uploads and downloads. | Read |
View Image Asset Inline view_asset | Inline an image asset (≤10MB) directly into the agent context for inspection. | Read |
Get Asset Download URL get_asset_download_url | Return a short-lived presigned URL the agent can use to save the asset to disk. | Read |
Initialize Asset Upload upload_asset_init | Begin uploading an image; returns a presigned URL. | Write |
Complete Asset Upload upload_asset_complete | Finalize an upload after bytes arrive in storage. | Write |
Initialize Batch Asset Upload upload_asset_init_batch | Begin uploading up to 50 images in one call. | Write |
Complete Batch Asset Upload upload_asset_complete_batch | Finalize a batch upload. | Write |
List Models list_models | Available generation models. | Read |
Get Model get_model | Pricing, inputs, and constraints for a model. | Read |
Get Job Status get_job_status | Status of a generation job. | Read |
List Project Jobs list_project_jobs | All generation jobs for a project. | Read |
Generate Asset generate | Generate media for an existing shot after model, prompt, count, and cost approval. | Write |
How auth works
Martini implements the OAuth 2.0 Protected Resource Metadata spec for MCP. When your client connects to either connector URL without a token, it receives a 401 with a WWW-Authenticate header that points to /.well-known/oauth-protected-resource. The metadata response advertises Supabase Auth as the authorization server.
From there, your client redirects you to sign in. Once you authorize the connection, your client receives a bearer token and uses it on subsequent requests. Tokens are scoped to your account; the connector never asks you for a password or API key directly.
All tool calls run as you, with the same project membership and write permissions you have in the Martini app.
Data handling
The connector reads and writes Martini data through the MCP client you connect. Tool responses are returned to that client on your behalf and may include project metadata, canvas structure, asset metadata, previews, subject details, text notes, variables, upload status, job status, and short-lived storage URLs. Specifically:
- We keep limited connection and tool activity records for security, abuse prevention, debugging, and reliability.
- Errors are reported to Sentry with your user ID and the tool name attached, to help us fix bugs.
- Generation jobs you submit through the connector use the same external AI providers as the in-app flow. Your prompts and reference images are sent to those providers under their own terms.
- Uploaded images are stored in Cloudflare R2 in your project, exactly as if you had uploaded them in the app.
See our Privacy Policy for the full breakdown.
Limits and quotas
Generation credits
Generations submitted through the full connector consume credits (“olives”) the same way as in-app generations. Claude should show the model, prompt, count, target shot or scene, and estimated cost before calling a generation tool. If you run out of credits, the tool call fails with a clear error and no charge. See the pricing page for credit costs per model.
Upload caps
Each image upload is capped at 25 MB. Batch upload tools accept up to 50 files per call. Supported image formats: JPEG, PNG, WebP. Audio and video uploads are not currently exposed through the connector — use the Martini app for those.
Rate limits
We don’t advertise a fixed per-minute rate limit yet, but we do enforce sane upper bounds at the storage and generation provider level. If you hit a transient error, retry with exponential backoff.
Policies
Use of the connector is governed by Martini’s Terms of Service and Privacy Policy. Generation jobs may also be subject to third-party model provider terms, as described in the Terms of Service.
Troubleshooting
“Origin not allowed”
The connector validates the Originheader on browser-based requests. If you’re using a browser-based MCP client from a domain other than claude.ai or claude.com, email support@martini.film and we’ll add you to the allowlist.
Uploads or downloads fail with a network error
If you’re calling Martini from an environment with restricted egress (e.g. a sandbox), R2 may be blocked for both uploads (PUT) and downloads (GET). Run the check_storage_reachability tool first — it returns a probe URL and a remediation message you can follow.
A generation hangs
Generations are queued through providers that occasionally have spikes in latency. Use get_job_status to poll. If a job is still running after 10 minutes for a model that normally finishes in under 2, contact support.
Support
Questions, bug reports, and feature requests: support@martini.film. Partnership and integration inquiries: hello@martini.film.