Skip to main content
Glama
LouisChanCLY

napkin-ai-mcp

by LouisChanCLY
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

CI npm version License: MIT

Disclaimer: This is an unofficial, community-maintained MCP server for Napkin AI. It is not affiliated with, endorsed by, or officially supported by Napkin AI or Second Layer, Inc. For official Napkin AI products and support, please visit napkin.ai.

API Compatibility: Tested with Napkin AI API v1.1.16. Newer API versions may introduce breaking changes.

An MCP (Model Context Protocol) server for generating infographics and visuals using the Napkin AI API. This server enables AI assistants like Claude to generate professional visuals from text content.

Features

  • Visual Generation: Generate SVG, PNG, or PPT visuals from text content

  • Multiple Visual Types: Mindmaps, flowcharts, timelines, comparisons, and more (see gallery)

  • Async Handling: Automatic polling for Napkin AI's async generation

  • Multi-Storage Support: Save generated visuals to:

    • Local filesystem

    • Amazon S3 (or S3-compatible services)

    • Google Drive

    • Slack

    • Notion

    • Telegram

    • Discord

  • Flexible Configuration: Environment variables or JSON config file

  • Full TypeScript Support: Comprehensive type definitions with Zod validation

  • Automatic Retries: Exponential backoff for transient failures (429, 5xx)

  • Debug Logging: Set NAPKIN_DEBUG=true for troubleshooting

  • Dry-Run Mode: Validate requests without calling the API

  • CLI Help: Run with --help for usage information

Related MCP server: Image MCP Server

Prerequisites

  • Node.js 18.x or later

  • A Napkin AI API key (currently in developer preview - contact api@napkin.ai)

Quick Start

Installation

npm install -g napkin-ai-mcp

Or use directly with npx:

npx napkin-ai-mcp

Get Your API Key

The Napkin AI API is currently in developer preview. To request access:

  1. Visit napkin.ai

  2. Contact api@napkin.ai for API access

Integration Guides

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

With local storage enabled:

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "/Users/yourname/napkin-visuals"
      }
    }
  }
}

After updating the config, restart Claude Desktop.

Claude Code (CLI)

Add to your Claude Code MCP settings:

Global config: ~/.claude/settings.json Project config: .claude/settings.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "./visuals"
      }
    }
  }
}

Or run the CLI command:

claude mcp add napkin-ai -- npx -y napkin-ai-mcp

Then set the environment variable:

export NAPKIN_API_KEY="your-api-key-here"

Cursor

Add to your Cursor MCP configuration:

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here",
        "NAPKIN_STORAGE_TYPE": "local",
        "NAPKIN_STORAGE_LOCAL_DIR": "./visuals"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

File: ~/.windsurf/mcp.json

{
  "mcpServers": {
    "napkin-ai": {
      "command": "npx",
      "args": ["-y", "napkin-ai-mcp"],
      "env": {
        "NAPKIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code with Continue

Add to your Continue configuration:

File: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "napkin-ai-mcp"],
          "env": {
            "NAPKIN_API_KEY": "your-api-key-here"
          }
        }
      }
    ]
  }
}

Cline (VS Code Extension)

Add to your Cline MCP settings in VS Code:

  1. Open VS Code settings

  2. Search for "Cline MCP"

  3. Add the server configuration:

{
  "napkin-ai": {
    "command": "npx",
    "args": ["-y", "napkin-ai-mcp"],
    "env": {
      "NAPKIN_API_KEY": "your-api-key-here"
    }
  }
}

Available Tools

Once configured, your AI assistant will have access to these tools:

Tool

Description

generate_visual

Submit a visual generation request (async)

check_status

Check the status of a generation request

download_visual

Download a generated visual as base64

generate_and_wait

Generate and wait for completion

generate_and_save

Generate and save to configured storage

list_styles

Get information about available styles

verify_api_key

Verify your API key is valid and working

Example Prompts

Once configured, try these prompts with your AI assistant:

  • "Create a mindmap visualising the key concepts of machine learning"

  • "Generate a flowchart showing the user registration process"

  • "Make a timeline of major events in the history of computing"

  • "Create an infographic comparing REST vs GraphQL APIs"

Configuration

Environment Variables

Variable

Description

Required

NAPKIN_API_KEY

Napkin AI API key

Yes

NAPKIN_API_BASE_URL

Custom API base URL

No

NAPKIN_STORAGE_TYPE

Storage type: local, s3, google-drive, slack, notion, telegram, discord

No

NAPKIN_POLLING_INTERVAL

Polling interval in ms (default: 2000)

No

NAPKIN_MAX_WAIT_TIME

Max wait time in ms (default: 300000)

No

Storage Configuration

Local Storage

Save visuals to a local directory:

NAPKIN_STORAGE_TYPE=local
NAPKIN_STORAGE_LOCAL_DIR=./output

Files are saved with the format: napkin-{request_id}-{index}-{color_mode}.{format}

Note for Claude Desktop users: Claude Desktop runs in a sandboxed environment and cannot access local filesystem paths. While files are saved successfully, Claude Desktop cannot display or open them directly. For Claude Desktop, consider using a cloud storage provider (S3, Google Drive, etc.) which returns accessible URLs. Claude Code has full filesystem access and works seamlessly with local storage.

Amazon S3

Save visuals to an S3 bucket (also works with S3-compatible services like MinIO, DigitalOcean Spaces, Cloudflare R2):

NAPKIN_STORAGE_TYPE=s3
NAPKIN_STORAGE_S3_BUCKET=my-bucket
NAPKIN_STORAGE_S3_REGION=eu-west-1
NAPKIN_STORAGE_S3_PREFIX=napkin-visuals/  # Optional path prefix
NAPKIN_STORAGE_S3_ENDPOINT=https://s3.example.com  # Optional, for S3-compatible services
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

Required IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject"],
      "Resource": "arn:aws:s3:::my-bucket/napkin-visuals/*"
    }
  ]
}

Google Drive

Save visuals to a Google Drive folder using a service account:

NAPKIN_STORAGE_TYPE=google-drive
NAPKIN_STORAGE_GDRIVE_FOLDER_ID=1ABC...xyz
NAPKIN_STORAGE_GDRIVE_CREDENTIALS=./service-account.json

Setup steps:

  1. Go to Google Cloud Console

  2. Create a new project or select an existing one

  3. Enable the Google Drive API

  4. Go to "IAM & Admin" → "Service Accounts" → "Create Service Account"

  5. Download the JSON key file and save as service-account.json

  6. Share your target Google Drive folder with the service account email (ends with @*.iam.gserviceaccount.com)

  7. Get the folder ID from the URL: https://drive.google.com/drive/folders/{FOLDER_ID}

Slack

Upload visuals to a Slack channel:

NAPKIN_STORAGE_TYPE=slack
NAPKIN_STORAGE_SLACK_CHANNEL=C0123456789
NAPKIN_STORAGE_SLACK_TOKEN=xoxb-your-bot-token

Setup steps:

  1. Go to Slack API and create a new app

  2. Under "OAuth & Permissions", add these Bot Token Scopes:

    • files:write - Upload files

    • chat:write - Post messages (optional)

  3. Install the app to your workspace

  4. Copy the "Bot User OAuth Token" (starts with xoxb-)

  5. Get the channel ID: right-click a channel → "View channel details" → scroll to the bottom

Note: The bot must be invited to the channel with /invite @your-bot-name

Notion

Upload visuals to a Notion page:

NAPKIN_STORAGE_TYPE=notion
NAPKIN_STORAGE_NOTION_TOKEN=secret_abc123...
NAPKIN_STORAGE_NOTION_PAGE_ID=12345678-abcd-1234-abcd-123456789abc
NAPKIN_STORAGE_NOTION_DATABASE_ID=optional-db-id  # Optional

Setup steps:

  1. Go to Notion Integrations and create a new integration

  2. Copy the "Internal Integration Token" (starts with secret_)

  3. Open the target Notion page and click "..." → "Add connections" → select your integration

  4. Get the page ID from the URL: https://notion.so/Page-Name-{PAGE_ID} (the 32-character ID at the end)

Note: Notion has file size limits. For large visuals, consider using S3 or Google Drive.

Telegram

Send visuals to a Telegram chat or channel:

NAPKIN_STORAGE_TYPE=telegram
NAPKIN_STORAGE_TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
NAPKIN_STORAGE_TELEGRAM_CHAT_ID=-1001234567890

Setup steps:

  1. Message @BotFather on Telegram and create a new bot with /newbot

  2. Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

  3. Add the bot to your group/channel as an admin (for channels) or member (for groups)

  4. Get the chat ID:

    • For groups: Add @userinfobot to the group, it will show the chat ID

    • For channels: Forward a message from the channel to @userinfobot

    • For private chats: Send a message to your bot, then visit https://api.telegram.org/bot<TOKEN>/getUpdates

Note: Channel IDs start with -100, group IDs are negative numbers, user IDs are positive.

Discord

Send visuals to a Discord channel via webhook:

NAPKIN_STORAGE_TYPE=discord
NAPKIN_STORAGE_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789/abcdef...
NAPKIN_STORAGE_DISCORD_USERNAME=Napkin AI  # Optional

Setup steps:

  1. Open Discord and go to the channel where you want to receive visuals

  2. Click the gear icon (Edit Channel) → Integrations → Webhooks → New Webhook

  3. Give it a name and optionally upload an avatar

  4. Click "Copy Webhook URL"

Note: No bot setup required - webhooks are the simplest way to post to Discord.

Default Visual Settings

NAPKIN_DEFAULT_FORMAT=svg       # svg, png, or ppt
NAPKIN_DEFAULT_LANGUAGE=en-GB   # BCP 47 language tag
NAPKIN_DEFAULT_COLOR_MODE=light # light, dark, or both
NAPKIN_DEFAULT_ORIENTATION=auto # auto, horizontal, vertical, or square

JSON Configuration

Create a config.json file:

{
  "napkinApiKey": "your-api-key",
  "storage": {
    "type": "local",
    "directory": "./visuals"
  },
  "defaults": {
    "format": "svg",
    "language": "en-GB",
    "color_mode": "light"
  }
}

Tool Parameters

generate_visual / generate_and_wait / generate_and_save

Parameter

Type

Description

content

string

Required. Text content to visualise

format

string

Output format: svg, png, or ppt (default: svg)

dry_run

boolean

Validate request without calling API (default: false)

context

string

Additional context for generation (not shown in visual)

language

string

BCP 47 language tag (e.g., en-GB). Default: en

style_id

string

Napkin AI style identifier. See styles

visual_id

string

Regenerate a specific visual layout with new content

visual_ids

string[]

Array of visual IDs (length must match number_of_visuals)

visual_query

string

Visual type: mindmap, flowchart, timeline, etc.

visual_queries

string[]

Array of visual queries (length must match number_of_visuals)

number_of_visuals

number

Variations to generate (1-4, default: 1)

transparent_background

boolean

Use transparent background (default: false)

color_mode

string

light, dark, or both (default: light)

width

number

Width in pixels (PNG only, 100-10000)

height

number

Height in pixels (PNG only, 100-10000)

orientation

string

auto, horizontal, vertical, or square

text_extraction_mode

string

auto, rewrite, or preserve (default: auto)

sort_strategy

string

relevance, random, or variation (default: relevance)

Note: visual_id/visual_ids and visual_query/visual_queries are mutually exclusive.

Example Output

Here are some examples of visuals generated using this MCP server. Each example shows the input text and the resulting visual.

Mind Map

Input text:

# Benefits of Visual Communication

## Speed
- Processed 60,000x faster than text
- Instant pattern recognition

## Retention
- 80% of what we see is remembered
- Only 20% of text is retained

## Engagement
- 94% more views than text-only
- Higher social sharing rates

Parameters: format: "svg", visual_query: "mindmap", language: "en-GB"

Mind Map Example

Flowchart

Input text:

# User Registration Flow

1. User clicks "Sign Up" button
2. Enter email address
3. System validates email format
4. If invalid, show error message
5. If valid, send verification email
6. User clicks verification link
7. Create password
8. Validate password strength
9. If strong, create account
10. Redirect to dashboard

Parameters: format: "svg", visual_query: "flowchart", language: "en-GB"

Flowchart Example

Timeline

Input text:

# History of Artificial Intelligence

## 1950
Alan Turing publishes "Computing Machinery and Intelligence"

## 1956
The term "Artificial Intelligence" is coined

## 1997
IBM's Deep Blue defeats world chess champion

## 2016
AlphaGo defeats Go world champion Lee Sedol

## 2022
ChatGPT launches, bringing LLMs to the mainstream

Parameters: format: "svg", visual_query: "timeline", language: "en-GB"

Timeline Example

See more examples at the Napkin AI Gallery.

Visual Query Types

  • mindmap - Mind map visualisations

  • flowchart - Process flows and diagrams

  • timeline - Chronological events

  • comparison - Side-by-side comparisons

  • hierarchy - Organisational structures

  • cycle - Cyclical processes

  • list - Bulleted or numbered lists

  • matrix - Grid-based comparisons

Programmatic Usage

import { NapkinClient, createNapkinMcpServer } from "napkin-ai-mcp";

// Use the client directly
const client = new NapkinClient({
  apiKey: "your-api-key",
});

const result = await client.generateAndWait({
  format: "svg",
  content: "# My Visual\n\n- Point 1\n- Point 2",
  visual_query: "mindmap",
});

// Download the file using the URL from generated_files
if (result.generated_files && result.generated_files.length > 0) {
  const buffer = await client.downloadFile(result.generated_files[0].url);
  // buffer contains the SVG content
}

Development

# Clone the repository
git clone https://github.com/LouisChanCLY/napkin-ai-mcp.git
cd napkin-ai-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Troubleshooting

"NAPKIN_API_KEY is required"

Ensure you've set the NAPKIN_API_KEY environment variable in your MCP configuration.

"Storage not configured"

The generate_and_save tool requires storage configuration. Add one of the storage configurations above.

Visual generation times out

Increase NAPKIN_MAX_WAIT_TIME (default: 300000ms = 5 minutes).

Connection issues

  1. Ensure Node.js 18+ is installed

  2. Check your API key is valid

  3. Verify network connectivity to api.napkin.ai

API Reference

Licence

MIT

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting pull requests.

Available Tools

7 tools
check_statusCheck Generation StatusA

Check the status of a visual generation request. Returns progress information and file details when completed.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYesRequest ID from generate_visual

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
errorNoError message if failed
statusYesCurrent status: pending, processing, completed, or failed
creditsNoCredit consumption for the request
generated_filesNoGenerated files when completed

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It discloses that the tool returns progress and file details, but it does not mention non-destructive behavior, polling limitations, or error conditions. This is adequate but minimal for a status check tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, clear sentences convey the purpose and return value with no filler. Well-structured and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter status tool, the description fully covers what the tool does and returns. The existence of an output schema means return format specifics need not be duplicated here. Sibling tools provide enough context for placement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the request_id parameter already described as 'Request ID from generate_visual.' The description adds no further parameter detail, so it does not exceed the baseline set by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Check' with a clear resource: 'status of a visual generation request.' It explicitly states what is returned ('progress information and file details'), making it distinct from sibling tools like generate_visual or download_visual.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after a generation request, reinforced by the parameter description 'Request ID from generate_visual.' However, it does not explicitly state when not to use this tool versus alternatives like generate_and_wait, though the context makes it reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_visualDownload VisualA

Download a generated visual file as base64-encoded data. Use the URL from check_status response's generated_files array.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_urlYesFile URL from check_status generated_files

Output Schema

ParametersJSON Schema
NameRequiredDescription
size_bytesYesFile size in bytes
content_base64YesBase64-encoded file content

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that output is base64-encoded data and that the input URL comes from check_status. However, it does not mention authentication requirements, potential failure modes (e.g., invalid URL), or any side effects. This is adequate for a simple download tool but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured: two sentences that front-load the action and output format, followed by a precise instruction on where to obtain the input. Every sentence earns its place, with no redundant or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter, output schema present), the description is almost complete. It covers the workflow (use check_status URL) and the output format (base64). A note about authentication or error handling would complete it, but the existing description is sufficient for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documentation already provides 100% coverage for the file_url parameter, including its format and source ('File URL from check_status generated_files'). The description's mention of the URL from check_status does not add information beyond what the schema already states, so it meets the baseline for schema-covered parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Download a generated visual file as base64-encoded data.' It uses a specific verb (download), identifies the resource (generated visual file), and specifies the output format (base64). This distinguishes it from siblings like generate_visual and check_status by focusing on the download step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: 'Use the URL from check_status response's generated_files array.' This tells the agent the prerequisite and source of the input parameter. However, it does not explicitly mention alternatives or when not to use this tool, such as generate_and_save, which might be a direct alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_and_saveGenerate Visual and SaveA

Generate a visual, wait for completion, and save to configured storage. Requires storage to be configured in server settings.

ParametersJSON Schema
NameRequiredDescriptionDefault
widthNoWidth in pixels (PNG only)
formatNoOutput format: svg, png, or ppt (default: svg)
heightNoHeight in pixels (PNG only)
contentYesMain text content to visualise
contextNoAdditional context for visual generation
dry_runNoValidate inputs without calling the API (default: false)
filenameNoCustom filename (without extension). Auto-generated if not provided.
languageNoBCP 47 language tag (e.g., en, en-GB). Default: en
style_idNoStyle identifier from Napkin AI
visual_idNoRegenerate a specific visual layout with new content. Cannot be used with visual_ids, visual_query, or visual_queries.
color_modeNoColour mode: light, dark, or both
visual_idsNoArray of visual IDs to regenerate specific layouts. Length must match number_of_visuals.
orientationNoOrientation: auto, horizontal, vertical, or square
visual_queryNoVisual type query (e.g., mindmap, flowchart, timeline)
sort_strategyNoSort strategy: relevance, random, or variation
visual_queriesNoArray of visual type queries. Length must match number_of_visuals.
number_of_visualsNoNumber of variations to generate (1-4)
text_extraction_modeNoText extraction: auto, rewrite, or preserve
transparent_backgroundNoUse transparent background

Output Schema

ParametersJSON Schema
NameRequiredDescription
filesYesSaved files with storage locations
creditsNoCredit consumption for the request
request_idYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It honestly states the side effect of saving and the asynchronous waiting behavior. Yet it omits details such as failure handling, return value semantics, or storage specifics, leaving some informational gaps beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently states the core workflow. Every word earns its place, with no filler or repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (19 parameters) and the rich schema and output schema, the description provides a minimal but adequate high-level overview. It covers the key workflow (generate, wait, save) but lacks contextual details about multi-visual generation, regeneration, or failure modes. These gaps are partially mitigated by the schema's parameter descriptions, making the description adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level meaning, but since the schema already documents all 19 parameters with descriptions and constraints, no extra compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Generate a visual, wait for completion, and save to configured storage.' This distinguishes it from siblings like generate_visual and generate_and_wait, which focused on generation without saving. The verb+resource structure is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: it generates, waits, and saves, and explicitly notes a prerequisite ('Requires storage to be configured in server settings'). However, it does not explicitly contrast with generate_and_wait or other alternatives, so I deduct one point for lacking explicit when-to-use vs. alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_and_waitGenerate Visual and WaitA

Generate a visual and wait for completion. Combines generate_visual and polling check_status into a single operation.

ParametersJSON Schema
NameRequiredDescriptionDefault
widthNoWidth in pixels (PNG only)
formatNoOutput format: svg, png, or ppt (default: svg)
heightNoHeight in pixels (PNG only)
contentYesMain text content to visualise
contextNoAdditional context for visual generation
dry_runNoValidate inputs without calling the API (default: false)
languageNoBCP 47 language tag (e.g., en, en-GB). Default: en
style_idNoStyle identifier from Napkin AI
visual_idNoRegenerate a specific visual layout with new content. Cannot be used with visual_ids, visual_query, or visual_queries.
color_modeNoColour mode: light, dark, or both
visual_idsNoArray of visual IDs to regenerate specific layouts. Length must match number_of_visuals.
orientationNoOrientation: auto, horizontal, vertical, or square
visual_queryNoVisual type query (e.g., mindmap, flowchart, timeline)
sort_strategyNoSort strategy: relevance, random, or variation
visual_queriesNoArray of visual type queries. Length must match number_of_visuals.
number_of_visualsNoNumber of variations to generate (1-4)
text_extraction_modeNoText extraction: auto, rewrite, or preserve
transparent_backgroundNoUse transparent background

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
statusYes
creditsNoCredit consumption for the request
generated_filesYesGenerated files with download URLs

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions waiting for completion, implying a blocking operation, but it doesn't disclose potential timeouts, failure modes, authentication requirements, or that it makes API calls. It also omits side effects like resource creation or quota consumption, leaving the agent insufficiently informed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero fluff. Every word contributes to understanding the tool's core function and composition. It is appropriately terse for a composite tool, though one could argue for more detail given complexity, conciseness is a strength.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 18 parameters and a composite operation, the description is extremely short. It names the two operations but doesn't cover orchestration details like polling interval, timeout, error handling, or how the waiting behaves with multiple visuals. An output schema exists but return values are not the gap; the tool's behavioral semantics remain underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides descriptions for all 18 parameters (100% coverage), so the description adds no parameter semantics. Baseline is 3 when schema coverage is high, and the description doesn't clarify interactions like visual_id vs visual_query, which the schema already documents individually.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's primary action: 'Generate a visual and wait for completion.' It distinguishes itself from siblings by explicitly mentioning it combines generate_visual and check_status into one operation, making its purpose unambiguous and unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by stating it combines generate_visual and polling check_status, signaling that this is the one-shot operation when you need the final completed visual. It references sibling tools indirectly but doesn't explicitly say when NOT to use it, such as when you need to poll manually or perform other tasks in between.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_visualGenerate VisualB

Submit a visual generation request to Napkin AI. Returns a request ID for tracking. Use check_status to poll for completion.

ParametersJSON Schema
NameRequiredDescriptionDefault
widthNoWidth in pixels (PNG only)
formatNoOutput format: svg, png, or ppt (default: svg)
heightNoHeight in pixels (PNG only)
contentYesMain text content to visualise
contextNoAdditional context for visual generation
dry_runNoValidate inputs without calling the API (default: false)
languageNoBCP 47 language tag (e.g., en, en-GB). Default: en
style_idNoStyle identifier from Napkin AI
visual_idNoRegenerate a specific visual layout with new content. Cannot be used with visual_ids, visual_query, or visual_queries.
color_modeNoColour mode: light, dark, or both
visual_idsNoArray of visual IDs to regenerate specific layouts. Length must match number_of_visuals.
orientationNoOrientation: auto, horizontal, vertical, or square
visual_queryNoVisual type query (e.g., mindmap, flowchart, timeline)
sort_strategyNoSort strategy: relevance, random, or variation
visual_queriesNoArray of visual type queries. Length must match number_of_visuals.
number_of_visualsNoNumber of variations to generate (1-4)
text_extraction_modeNoText extraction: auto, rewrite, or preserve
transparent_backgroundNoUse transparent background

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYesRequest ID for tracking
statusYesInitial status (usually 'pending')
warningNoAny warnings from the API

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It only discloses that a request ID is returned, leaving out important behavioral details such as authentication requirements, rate limits, or whether execution is synchronous or asynchronous. Even the async nature is only implied through the polling reference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary action, and no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description is minimal for an async tool with 18 parameters and several sibling tools. It fails to mention prerequisites (e.g., API key), processing expectations, or how it differs from generate_and_wait beyond returning a request ID. The description does not fully map the tool's role within the broader toolset.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 18 parameters thoroughly. The description adds no parameter-specific meaning, and the baseline of 3 is appropriate since the heavy lifting is done by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Submit a visual generation request to Napkin AI') and resource. It distinguishes from sibling tools by noting it returns a request ID and pointing to check_status for polling, unlike generate_and_wait or generate_and_save.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a clear workflow (submit then poll with check_status) but does not explicitly mention when to prefer this tool over alternatives like generate_and_wait, nor does it state any exclusions. The guidance is more implied than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_stylesList Available StylesB

Get information about available visual styles. Note: For the full list, visit https://api.napkin.ai/docs/styles/index.html

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
messageYes
styles_urlYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description must carry the full burden. It only says 'Get information' without disclosing return format, pagination, or that the response is not exhaustive. The note about the full list is the only behavioral caveat, but it is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the main action. The note about the website is relevant and doesn't waste words. It is appropriately sized for a simple tool, though it lacks depth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values are covered, but the description lacks guidance on how this tool fits into the workflow (e.g., getting styles before generating visuals). The absence of annotations and usage context makes it incomplete for an agent to know when to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the baseline score is 4. The schema is empty, so there is no parameter information to add, and the description doesn't need to explain any.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves information about visual styles, which is a specific resource. It distinguishes from sibling tools that generate, check, or download visuals, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool compared to alternatives. The note about the full list URL is a weak hint about potential limitations, but it doesn't provide clear context or exclusions for using this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_api_keyVerify API KeyA

Verify that the configured Napkin AI API key is valid. Use this to test your setup before generating visuals.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoError message if invalid
validYesWhether the API key is valid
base_urlYesAPI base URL being used

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It states the tool verifies validity, implying a read-only check, but does not explain what happens on failure, whether it makes a network request, or what the response contains. The existing output schema may cover return format, but the description lacks richer behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, directly states the purpose and usage, and contains no filler or redundant information. It is well-structured and easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, output schema present, low complexity), the description is nearly complete. It conveys the purpose and when to use it. The only minor gap is the lack of detail on failure behavior, but this does not significantly impact usability for a simple API key check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds value by indicating the tool tests the configured API key, which gives context for why there are no user-supplied inputs. No additional parameter semantics are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Verify') and the resource ('configured Napkin AI API key'), with a specific objective ('is valid'). It is distinct from sibling tools like generate_visual or download_visual, which perform different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Use this to test your setup before generating visuals' provides explicit context for when to use the tool. It does not mention alternatives or exclusions, but for a simple validation tool with zero parameters, this guidance is sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.2.0
    • First observedcheck_status
    • First observeddownload_visual
    • First observedgenerate_and_save
    • First observedgenerate_and_wait
    • First observedgenerate_visual
    • First observedlist_styles
    • First observedverify_api_key
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Most tools have distinct purposes, but generate_visual, generate_and_wait, and generate_and_save all trigger visual generation with different behaviors, which could cause confusion. Description clarifies the differences though, and the other tools (check_status, download_visual, list_styles, verify_api_key) are clearly separate.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (generate_visual, check_status, download_visual, list_styles, verify_api_key). The compound names generate_and_wait and generate_and_save are also consistent with this style, making the set predictable.

Tool Count5/5

Seven tools is well-scoped for a visual generation service, covering submission, status polling, download, convenience wrappers, style listing, and API key verification. Each tool serves a clear function without unnecessary redundancy.

Completeness4/5

The core lifecycle of generating, checking, and downloading visuals is fully covered, plus useful extras like styles and API key verification. Minor gaps exist (e.g., no cancel request or delete operation), but these are not essential for the primary use case.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Image MCP Server

    iplanwebsites
    A
    license
    C
    quality
    C
    maintenance
    An MCP server that provides AI image generation capabilities using OpenAI and Replicate APIs with support for customizable prompts and dimensions. It features specialized tools for generating square, landscape, and portrait images through simple natural language commands.
    5
    26 npm
    MIT

  • Datawrapper MCP

    hqu
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI assistants to create, update, and publish Datawrapper charts through natural language. It provides tools for data synchronization, visual configuration, and retrieving chart images or editor links.
    8
    MIT

  • Azure Diagram MCP Server

    Jah-yee
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that generates professional infrastructure diagrams using the Python diagrams DSL, with first-class Azure support and GitHub Copilot integration for natural language diagram generation.
    4
    MIT