MCP tools reference
Authentication, tools, parameters, and error handling for the Gamma MCP server.
Complete reference for the Gamma MCP server's authentication, available tools, input parameters, and error handling.
Quick reference
All requests require an OAuth 2.0 Bearer token.
Available tools:
generate,generate_multi_page_gamma,generate_from_template,get_generation_status,generate_image,get_image_generation_status,export_gamma,get_export_status,get_gammas,read_gamma,get_gamma_comments,get_gamma_analytics,get_gamma_card_analytics,get_gamma_viewer_analytics,get_gamma_viewer_detail_analytics,get_themes, andget_folders.generate,generate_multi_page_gamma, andgenerate_from_templateare asynchronous. They return agenerationId; callget_generation_statusuntilstatusiscompletedorfailed.export_gammais asynchronous. It returns anexportId; callget_export_statusuntilstatusiscompletedorfailed.generate_imagecreates a standalone image and is asynchronous. It returns animageGenerationId; callget_image_generation_statusuntilstatusiscompletedorfailed.Use
get_gammasto browse existing gammas and templates, andread_gamma(read-only, accepts a file ID or full URL) to read one.Analytics tools (
get_gamma_analytics,get_gamma_card_analytics,get_gamma_viewer_analytics,get_gamma_viewer_detail_analytics) report engagement for an existing gamma; data is eventually consistent and can lag by about an hour.OAuth discovery is available at
/.well-known/oauth-protected-resource.Errors return
{ "error": "...", "isError": true }.
Authentication
The Gamma MCP server uses OAuth 2.0. Every request must include a valid Bearer token. For a walkthrough of the same OAuth flow against the REST API, see Authenticate with OAuth.
Authorization header
Include your token with each request:
OAuth discovery
The server implements RFC 9728 (OAuth Protected Resource Metadata). Clients retrieve OAuth configuration at:
Dynamic client registration
The authorization server supports RFC 7591 Dynamic Client Registration. Discover the registration endpoint URL from the authorization server metadata obtained via the OAuth discovery endpoint above.
OAuth consent permissions
When a user connects your app, Gamma asks them to approve these permissions:
Create gammas in your workspace
Read gammas in your workspace
List folders from your workspace
List themes from your workspace
Authentication errors
A failed authentication returns 401 Unauthorized with a WWW-Authenticate header:
Use the resource_metadata URI to discover the authorization server and initiate the OAuth flow.
Tools overview
generate
Create presentations, documents, webpages, or social posts from scratch
No
No
No
generate_multi_page_gamma
Create one multi-page Gamma (several pages under one URL) in a single request
No
No
No
generate_from_template
Create a new gamma from an existing template gamma
No
No
No
get_generation_status
Check the status of a generate, generate_multi_page_gamma, or generate_from_template job
Yes
No
Yes
generate_image
Generate one standalone image from a text prompt
No
No
No
get_image_generation_status
Check the status of a generate_image job and get the image URL
Yes
No
Yes
export_gamma
Export an existing gamma to PDF, PPTX, or PNG
No
No
No
get_export_status
Check the status of an export and get the download link
Yes
No
Yes
get_gammas
Browse or search existing gammas and templates
Yes
No
Yes
read_gamma
Read the full content of an existing Gamma
Yes
No
Yes
get_gamma_comments
List comment threads (and replies) on an existing Gamma
Yes
No
Yes
get_gamma_analytics
Get engagement summary analytics for a Gamma
Yes
No
Yes
get_gamma_card_analytics
Get card-by-card engagement for a Gamma
Yes
No
Yes
get_gamma_viewer_analytics
List the people who viewed a Gamma
Yes
No
Yes
get_gamma_viewer_detail_analytics
Get one viewer's detailed engagement with a Gamma
Yes
No
Yes
get_themes
Browse or search the Gamma theme library
Yes
No
Yes
get_folders
Browse or search your Gamma folders
Yes
No
Yes
generate
Create a new presentation, document, webpage, or social post from scratch. Each call creates new content and returns a generation job.
Input parameters
inputText
string
Yes
Content to generate from: a brief prompt, outline, or full draft
title
string
No
Title for the generated Gamma (1–500 characters); inferred from content if omitted
textMode
enum
No
How to handle the input text: generate, condense, or preserve
format
enum
No
Output type: presentation, document, social, or webpage
numCards
int
No
Number of slides, cards, or pages to generate
cardSplit
enum
No
How content is divided into cards: auto or inputTextBreaks
themeId
string
No
Theme ID from get_themes
folderIds
array[string]
No
At most one folder ID from get_folders
additionalInstructions
string
No
Extra guidance for the generator
exportAs
enum
No
Export format: pptx, pdf, or png. png returns a .zip with one PNG per card
Text options
Optional textOptions object for controlling text generation.
amount
enum
Text density per slide or section: brief, medium, detailed, extensive
tone
string
Writing tone, such as professional or casual
audience
string
Target audience, such as executives or students
language
string
Language code, such as en, es, or fr
Image options
Optional imageOptions object for controlling image sourcing.
source
enum
Image source: aiGenerated, webAllImages, webFreeToUse, webFreeToUseCommercially, pictographic, giphy, pexels, themeAccent, placeholder, or noImages
model
string
AI image model to use when source is aiGenerated
stylePreset
enum
Art style preset: photorealistic, illustration, abstract, 3D, lineArt, or custom
style
string
Custom style description for AI images when stylePreset is custom or omitted
Card options
Optional cardOptions object for layout and header/footer configuration.
dimensions
enum
Aspect ratio or page size: 16x9, 4x3, fluid, letter, a4, pageless, 1x1, 4x5, 9x16
headerFooter
object
Header and footer configuration
The headerFooter object contains six slot positions and two visibility flags. All properties are optional.
topLeft
object
Top-left header slot
topCenter
object
Top-center header slot
topRight
object
Top-right header slot
bottomLeft
object
Bottom-left footer slot
bottomCenter
object
Bottom-center footer slot
bottomRight
object
Bottom-right footer slot
hideFromFirstCard
boolean
Hide header/footer from the first card
hideFromLastCard
boolean
Hide header/footer from the last card
Each slot object accepts:
type
enum
Yes
Content type: cardNumber, image, or text
source
enum
No
Image source when type is image: themeLogo or custom
src
string
No
Image URL when type is image and source is custom
value
string
No
Text content when type is text
size
enum
No
Image size: sm, md, lg, xl
Sharing options
Optional sharingOptions object for controlling access after generation.
workspaceAccess
enum
Workspace member access: edit, comment, view, noAccess, fullAccess
externalAccess
enum
External user access: edit, comment, view, noAccess
emailOptions
object
Share via email to specific recipients
emailOptions accepts:
recipients
array[string]
Yes
Email addresses to share with
access
enum
Yes
Recipient access level: edit, comment, view, fullAccess
Output
generationId
string
Unique ID for the generation
status
enum
Initial status is pending
gammaUrl
string
Link to the generation in Gamma when available
Call get_generation_status with the returned generationId until the job reaches completed or failed.
generate_from_template
Create a new gamma by adapting, remixing, or transforming an existing template gamma. Use get_gammas with type: template if you need to find the right template ID first.
Input parameters
gammaId
string
Yes
File ID of the template gamma to use
prompt
string
Yes
Instructions and/or content for the new gamma
title
string
No
Title for the generated Gamma (1–500 characters); inferred from content if omitted
themeId
string
No
Theme ID from get_themes
imageOptions
object
No
Optional AI image overrides for templates that use AI-generated images
sharingOptions
object
No
Sharing and permissions options
folderIds
array[string]
No
At most one folder ID from get_folders
exportAs
enum
No
Export format: pptx, pdf, or png. png returns a .zip with one PNG per card
imageOptions accepts:
model
string
AI image model to use
style
string
Custom style description for AI-generated images
Output
generationId
string
Unique ID for the generation
status
enum
Initial status is pending
gammaUrl
string
Link to the generation in Gamma when available
warnings
string
File-level warnings about ignored or adjusted options (for example, sharing, folder, or dimension settings)
Call get_generation_status with the returned generationId until the job reaches completed or failed.
generate_multi_page_gamma
Create a single Gamma containing several distinct pages under one URL in one request — ideal for sales rooms, proposal sites, onboarding portals, and microsites. Prefer generate for a single presentation, document, webpage, or social post; use this only when the user wants several distinct pages within one Gamma. This tool creates new content and cannot edit an existing Gamma.
Input parameters
Provide pages[] in the order the pages should appear. Per-page settings live on each entry; file-wide settings (theme, folders, dimensions, sharing, export, overall title) apply to all pages.
pages
array[object]
Yes
Ordered list of pages to generate (1–50). Each entry becomes a distinct page with its own deep link
title
string
No
Title for the overall Gamma (1–500 characters); inferred if omitted
publish
boolean
No
When true, publish the result as a live multi-page site on a Gamma-generated subdomain once all pages succeed
themeId
string
No
Theme ID from get_themes
folderIds
array[string]
No
At most one folder ID from get_folders
cardOptions
object
No
Layout and header/footer configuration — same shape as the generate tool's card options
exportAs
enum
No
Export format: pptx, pdf, or png. png returns a .zip with one PNG per card
Each pages[] entry accepts:
inputText
string
Yes
Content to generate this page from
title
string
No
Title for this page (1–500 characters)
path
string
No
URL slug for this page, e.g. /pricing (1–500 characters). Honored only for pages after the first; omitted → derived from the title
additionalInstructions
string
No
Extra guidance for the generator
textMode
enum
No
How to handle the input text: generate (default), condense, or preserve
format
enum
No
Output type: presentation, document, social, or webpage
numCards
int
No
Number of cards to generate for this page
cardSplit
enum
No
How content is divided into cards: auto or inputTextBreaks
Output
generationId
string
Unique ID for the generation
status
enum
Initial status is pending
gammaUrl
string
Link to the generation in Gamma when available
pages
array[object]
Per-page results: gammaId, gammaUrl, status, and error / exportUrl when applicable
warnings
string
File-level warnings about ignored or adjusted options
Call get_generation_status with the returned generationId until the job reaches completed or failed.
get_generation_status
Check the status of a generation started with generate, generate_multi_page_gamma, or generate_from_template.
Input
generationId
string
Yes
Generation ID returned by the create tool
Output
generationId
string
Unique ID for the generation
status
enum
pending, completed, or failed
gammaUrl
string
URL to the created Gamma when the job is completed
exportUrl
string
Download URL for the export file when available. For exportAs: png, this is a .zip with one PNG per card. Expires after about one week; treat the URL as a secret
credits.deducted
int
Credits deducted for the generation
credits.remaining
int
Remaining credits after the generation
error
string
Error message when the generation fails
generate_image
Generate one standalone image from a text prompt — an illustration, scene, photo, or abstract graphic on its own, not a gamma.
This tool is asynchronous: it returns immediately with an imageGenerationId and status: pending. Call get_image_generation_status with that ID until the image is ready — do not call generate_image again to check progress, as that starts a new, separately billed generation.
Input
prompt
string
Yes
Description of the image to generate (1–5,000 characters). Include background treatments here too, such as "on a white background"
type
enum
No
Visual style: illustration (default), scene (narrative illustration), photo (photorealistic), or abstract
sizePreset
enum
No
Aspect ratio: social-square (1:1, default), social-portrait (4:5), story (9:16), banner (16:9), or slide (16:9). Exact pixel dimensions are chosen by the model
themeId
string
No
Theme ID from get_themes to brand the image; omit for the workspace default theme
referenceImages
array[object]
No
Up to 4 reference images whose subject (a character or product) should appear in the generated image. Each entry accepts url (required, must be https://) and role (only subject is supported)
When referenceImages are provided, the references drive the look and type and themeId are ignored.
Output
imageGenerationId
string
Unique ID for the image generation
status
enum
Initial status is pending
warnings
array[object]
Warnings about ignored or adjusted options, each with code and message
Image generations charge credits. Call get_image_generation_status with the returned imageGenerationId until the job reaches completed or failed.
get_image_generation_status
Check the status of an image generation started with generate_image, and retrieve the image URL once it is ready. Each call returns the current status; poll it every few seconds rather than in a tight loop.
Input
imageGenerationId
string
Yes
Image generation ID returned by generate_image
Output
imageGenerationId
string
Unique ID for the image generation
status
enum
pending, completed, or failed
image
object
The generated image when completed: url, width, height, and aspectRatioUsed
warnings
array[object]
Warnings about ignored or adjusted options, each with code and message
error
string
Error message when the generation fails
retryable
boolean
Present on failure: whether retrying the same request could succeed. Invalid input, such as an unknown themeId or a blocked reference image URL, is not retryable
credits.deducted
int
Credits deducted for the generation
credits.remaining
int
Remaining credits after the generation
export_gamma
Export an existing gamma to a downloadable file. This starts the export and returns immediately with an exportId; the export runs in the background. Call get_export_status with that exportId to get the download link once it is ready — do not call export_gamma again to check progress, as that starts a new export.
Input
gammaIdOrUrl
string
Yes
Gamma file ID or full Gamma URL. Example: g5aykcic8ujm71s or https://gamma.app/docs/My-Deck-g5aykcic8ujm71s
exportAs
enum
Yes
Export format: pdf, pptx, or png. png returns a .zip with one PNG per card
Output
exportId
string
Unique ID for the export job
status
enum
Initial status is pending
gammaId
string
File ID of the gamma being exported
exportAs
enum
The requested export format
The connected user must have view access to the gamma in the selected workspace. Archived gammas cannot be exported. Call get_export_status with the returned exportId until the job reaches completed or failed.
get_export_status
Check the status of an export started with export_gamma, and retrieve the download link once it is ready.
Input
exportId
string
Yes
Export ID returned by export_gamma
Output
exportId
string
Unique ID for the export job
status
enum
pending, completed, or failed
gammaId
string
File ID of the exported gamma
exportAs
enum
The requested export format
exportUrl
string
Download URL when the export is completed. For exportAs: png, this is a .zip with one PNG per card. Anyone with this URL can download the file until it expires (about one week), and access is not tied to your API key, so treat the link as a secret
error
string
Customer-safe error message when the export fails
reason
enum
Machine-readable failure reason when the export fails: render_timeout, deck_too_large, no_content, or export_failed
get_gammas
Browse or search the user's existing gammas, including templates.
Input parameters
query
string
Search gammas by title; minimum 3 characters
type
enum
Filter by gamma type: template, regular, or all
limit
int
Maximum number of results to return; default 25, max 50
after
string
Cursor from a previous response for pagination
When paginating, keep query and type the same between calls and only advance the after cursor.
Output
gammas
array[object]
Array of matching gammas
gammas[].id
string
Unique gamma identifier
gammas[].title
string
Gamma title
gammas[].type
enum
template or regular
gammas[].url
string
URL to open the gamma
gammas[].thumbnailUrl
string | null
Thumbnail image URL when available
gammas[].themeId
string | null
Theme ID when available
gammas[].createdTime
string
ISO-8601 timestamp of creation time
gammas[].updatedTime
string
ISO-8601 timestamp of last modification
hasMore
boolean
Whether additional results are available
nextCursor
string
Cursor for the next page when more results exist
read_gamma
Read the content of an existing Gamma presentation or document. Use this when you want to inspect, reference, or learn from a Gamma that already exists.
This tool is read-only and idempotent. It cannot edit the Gamma.
Input
gammaIdOrUrl
string
Yes
Gamma file ID or full Gamma URL. Example: g5aykcic8ujm71s or https://gamma.app/docs/My-Deck-g5aykcic8ujm71s
Response format
Returns formatted text that includes the Gamma title and the full content of every page in order. The tool is designed to surface human-readable content, not raw HTML or JSON.
Title: <gamma title>identifies the Gamma title.=== Page N: <title> ===marks each page or card in original order.Each page body contains the full human-readable content for that page, including text, images, videos, embeds, charts, tables, diagrams, and other visuals.
The connected user must have view access to the Gamma in the selected workspace. Archived gammas cannot be read.
get_themes
Browse or search the Gamma theme library. Use the returned id in the generate or generate_from_template tool's themeId parameter.
If the user references a theme by name, search by name. Otherwise, fetch the full list and choose based on tone and color keywords.
Input parameters
name
string
Optional. Search themes by name
Output
themes
array[object]
Array of theme objects
themes[].id
string
Theme ID to pass to a generation tool
themes[].name
string
Display name
themes[].type
enum
standard or custom
themes[].colorKeywords
array[string]