> For the complete documentation index, see [llms.txt](https://developers.gamma.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gamma.app/mcp/mcp-tools-reference.md). # MCP tools reference 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_from_template`, `get_generation_status`, `get_gammas`, `read_gamma`, `get_themes`, and `get_folders`. * `generate` and `generate_from_template` are asynchronous. They return a `generationId`; call `get_generation_status` until `status` is `completed` or `failed`. * Use `get_gammas` to browse existing gammas and templates. * `read_gamma` accepts a Gamma file ID or full Gamma URL and is read-only. * 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. ### Authorization header Include your token with each request: ``` Authorization: Bearer ``` ### OAuth discovery The server implements [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth Protected Resource Metadata). Clients retrieve OAuth configuration at: ``` GET /.well-known/oauth-protected-resource ``` ### Dynamic client registration The authorization server supports [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) 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: ``` WWW-Authenticate: Bearer resource_metadata="https:///.well-known/oauth-protected-resource" ``` Use the `resource_metadata` URI to discover the authorization server and initiate the OAuth flow. ## Tools overview | Tool | Description | Read-only | Destructive | Idempotent | | ------------------------ | ----------------------------------------------------------------------- | --------- | ----------- | ---------- | | `generate` | Create presentations, documents, webpages, or social posts from scratch | 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 generation | 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_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 | Parameter | Type | Required | Description | | ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------ | | `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 | Folder IDs 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. | Parameter | Type | Description | | ---------- | -------- | ----------------------------------------------------------------------------- | | `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. | Parameter | Type | Description | | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | Parameter | Type | Description | | -------------- | -------- | --------------------------------------------------------------------------------------------------- | | `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. | Parameter | Type | Description | | ------------------- | --------- | -------------------------------------- | | `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: | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------ | | `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. | Parameter | Type | Description | | ----------------- | -------- | ---------------------------------------------------------------------------- | | `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: | Parameter | Type | Required | Description | | ------------ | --------------- | -------- | --------------------------------------------------------------- | | `recipients` | `array[string]` | Yes | Email addresses to share with | | `access` | `enum` | Yes | Recipient access level: `edit`, `comment`, `view`, `fullAccess` | ### Output | Field | Type | Description | | -------------- | -------- | ---------------------------------------------- | | `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 | Parameter | Type | Required | Description | | ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------ | | `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 | Folder IDs from `get_folders` | | `exportAs` | `enum` | No | Export format: `pptx`, `pdf`, or `png`. `png` returns a `.zip` with one PNG per card | `imageOptions` accepts: | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------ | | `model` | `string` | AI image model to use | | `style` | `string` | Custom style description for AI-generated images | ### Output | Field | Type | Description | | -------------- | -------- | --------------------------------------------------- | | `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` | Non-fatal warnings about ignored or adjusted inputs | 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` or `generate_from_template`. ### Input | Parameter | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------- | | `generationId` | `string` | Yes | Generation ID returned by the create tool | ### Output | Field | Type | Description | | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `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 | | `credits.deducted` | `int` | Credits deducted for the generation | | `credits.remaining` | `int` | Remaining credits after the generation | | `error` | `string` | Error message when the generation fails | ## get\_gammas Browse or search the user's existing gammas, including templates. ### Input parameters | Parameter | Type | Description | | --------- | -------- | ----------------------------------------------------------- | | `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 | Field | Type | Description | | ----------------------- | ---------------- | ------------------------------------------------ | | `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 | Parameter | Type | Required | Description | | -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `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: ` identifies the Gamma title. * `=== Page N: ===` 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 | Parameter | Type | Description | | --------- | -------- | ------------------------------- | | `name` | `string` | Optional. Search themes by name | ### Output | Field | Type | Description | | ------------------------ | --------------- | ------------------------------------- | | `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]` | Color keywords describing the palette | | `themes[].toneKeywords` | `array[string]` | Tone keywords describing the style | | `count` | `int` | Total themes returned | ## get\_folders Browse or search your Gamma folders. Use the returned `id` in a generation tool's `folderIds` parameter. ### Input parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------- | | `name` | `string` | Optional. Search folders by name | ### Output | Field | Type | Description | | ---------------- | --------------- | -------------------------------------- | | `folders` | `array[object]` | Array of folder objects | | `folders[].id` | `string` | Folder ID to pass to a generation tool | | `folders[].name` | `string` | Display name | | `count` | `int` | Total folders returned | ## Error handling All tools return errors in a consistent format: {% code title="Error response" %} ```json { "error": "Error message describing what went wrong", "isError": true } ``` {% endcode %} | Error | Description | | ---------------------- | ----------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Missing or invalid OAuth Bearer token | | `403 Forbidden` | The connected user does not have permission to access the requested Gamma or workspace resource | | `404 Not found` | The requested Gamma, generation, or resource could not be found | | `400 Bad request` | One or more parameters are invalid for the requested tool | | `Rate limit exceeded` | Too many requests in a given time period | | `Network connectivity` | Unable to establish connection to the server | | `Insufficient credits` | The account does not have enough credits to complete the generation | ## Related * [Set up the MCP server](/mcp/gamma-mcp-server.md) for getting started and troubleshooting * [Connect integrations](/connectors/connectors-and-integrations.md) for platform-specific setup * [Generate from text](/guides/generate-api-parameters-explained.md) for the equivalent REST API parameters * [Access and pricing](/get-started/access-and-pricing.md) for credit costs and plan details --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.gamma.app/mcp/mcp-tools-reference.md?ask=<question> ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.