Connect your agent with MCP.

Connect your client

1. Sign in to account settings.
2. Create a key with the MERMAID_RENDER permission.
3. Copy the key into your client's secret settings. The complete key is shown only once.
4. Add the server with the values below.

Server URL

https://www.mermaiddesk.com/api/mcp

Transport

Streamable HTTP

Header name

Authorization

Header value

Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your key. Keep it out of URLs and source control.

Your client must support custom authorization headers. This server does not support OAuth or the older SSE transport.

Connect and list tools. With the render permission, the list includes validate_mermaid and render_mermaid.

Set up your integration

Use a key with MERMAID_RENDER permission. The client must send that key with each request. These instructions follow the client documentation checked on 26 October 2026.

For local clients, set MERMAIDDESK_API_KEY in the environment that starts the app. Replace the placeholder below with your key. A terminal variable is available only to that terminal and the programs it starts.

export MERMAIDDESK_API_KEY='YOUR_API_KEY'

$env:MERMAIDDESK_API_KEY = 'YOUR_API_KEY'

[mcp_servers.mermaiddesk]
url = "https://www.mermaiddesk.com/api/mcp"
bearer_token_env_var = "MERMAIDDESK_API_KEY"

{
  "mcpServers": {
    "mermaiddesk": {
      "type": "http",
      "url": "https://www.mermaiddesk.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MERMAIDDESK_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "mermaiddesk": {
      "url": "https://www.mermaiddesk.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MERMAIDDESK_API_KEY}"
      }
    }
  }
}

For other clients, use Streamable HTTP with the URL and bearer header above. After setup, ask the agent to list its tools and validate the example below. Confirm that validate_mermaid returns a result.

Validate Mermaid

Ask your agent to call validate_mermaid with the Mermaid source. Correct the reported errors before you render or save.

{
  "name": "validate_mermaid",
  "arguments": { "source": "flowchart LR\n  App --> API" }
}

This is the argument to the SDK's callTool method. It is not a complete HTTP request.

Read structuredContent.valid. A value of false means the source has syntax errors. Use structuredContent.diagnostic to correct them.

Validation saves no diagram. It does not use your monthly render allowance. It does not check the meaning of a diagram.

Run a complete SDK example

Use Node.js 22 or later. Install the client package. Replace YOUR_API_KEY with your key.

npm install @modelcontextprotocol/client@2.4.0
export MERMAIDDESK_API_KEY='YOUR_API_KEY'

npm install @modelcontextprotocol/client@2.4.0
$env:MERMAIDDESK_API_KEY = 'YOUR_API_KEY'

Save this code as validate-mcp.mjs. Run node validate-mcp.mjs in the same terminal.

import {
  Client,
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/client";

const key = process.env.MERMAIDDESK_API_KEY;
if (!key) throw new Error("Set MERMAIDDESK_API_KEY.");

const client = new Client(
  { name: "diagram-agent", version: "1.0.0" },
  { versionNegotiation: { mode: "auto" } },
);
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL("https://www.mermaiddesk.com/api/mcp"),
    { requestInit: { headers: { Authorization: `Bearer ${key}` } } },
  ));

  const { tools } = await client.listTools();
  console.log(tools.map((tool) => tool.name));

  const result = await client.callTool({
    name: "validate_mermaid",
    arguments: { source: "flowchart LR\n  App --> API" },
  });
  if (result.isError) throw new Error(JSON.stringify(result.structuredContent));
  const data = result.structuredContent;
  if (data?.valid !== true) throw new Error(JSON.stringify(data));
  console.log("Mermaid syntax is valid.");
} finally {
  await client.close();
}

The script prints the available tool names. It then prints Mermaid syntax is valid.

Check a README diagram before you commit

Your agent can check a Mermaid block without saving a diagram in MermaidDesk. Use this sequence before it updates your documentation.

1. Validate the source

This example is missing a closing ] after the Web app label. Send the source inside the Markdown code fence to validate_mermaid.

flowchart LR
  App["Web app" --> API["API"]

2. Read the error details

The tool returns structuredContent.valid: false and a parse diagnostic for line 2. Read diagnostic.summary and diagnostic.sourceLine. This is a shortened result; the full response contains more error details.

{
  "valid": false,
  "diagnostic": {
    "stage": "parse",
    "line": 2,
    "sourceLine": "  App[\"Web app\" --> API[\"API\"]"
  }
}

3. Correct the source and validate again

Add the missing bracket, then call validate_mermaid again with the corrected source.

flowchart LR
  App["Web app"] --> API["API"]

{ "valid": true }

A valid result confirms syntax only. Check the diagram against the actual code and system before you put it in the README. Validation does not check that relationship or guarantee the rendered layout.

Give your agent this instruction

Before you update Mermaid blocks in README.md:
1. Check the diagram against the code. State any assumptions.
2. Call MermaidDesk's validate_mermaid tool for each block.
3. If valid is false, use the diagnostic to correct the source.
4. Validate the corrected source again. Stop after three attempts
   and report any remaining errors.
5. Update the README only after validation succeeds and you have
   checked the diagram against the code.
Do not save or publish a diagram in MermaidDesk for this task.
A valid result confirms syntax only, not system accuracy.

Use the tools

After validation, call render_mermaid with a format and an optional theme.

{
  "name": "render_mermaid",
  "arguments": {
    "source": "flowchart LR\n  App --> API",
    "format": "svg",
    "theme": "light"
  }
}

SVG arrives as text in an embedded resource. PNG arrives as an image block. PDF arrives as a blob resource. These are inline files, not download URLs.

For authenticated file downloads, use the REST API.

list_diagrams
get_diagram

Find and read private diagrams. Add read permission.

create_diagram

Save a private diagram. Send source and a unique idempotencyKey. Add write permission.

update_diagram
delete_diagram

Edit or delete a diagram. Add write permission. Updates require expectedUpdatedAt from the latest read.

export_diagram

Export saved source with read permission. Add render permission for SVG, PNG, or PDF.

publish_diagram
revoke_diagram_publication

Publish or revoke a public snapshot. Add share permission. Publication also requires read permission.

Tool discovery includes the input schemas. Only tools allowed by the key's permissions appear.

Reuse the same creation key and payload after a lost response. For updates, read the diagram first and send its exact updatedAt value as expectedUpdatedAt.

Publication also requires expectedUpdatedAt. Publish only when you intend to make the saved source public. Revoking a key does not revoke public snapshots.

Fix connection errors

Client asks for OAuth

Use a client that supports Streamable HTTP with a custom bearer header.

401 Unauthorized

Check the key and the Bearer prefix. Replace a revoked key.

403 Forbidden

Use the exact server URL above, including www. Cross-origin browser clients cannot connect.

A tool is missing

Check the key permissions. Reconnect and refresh the tool list.

405 on GET or DELETE

The server does not keep sessions. Use Streamable HTTP POST requests through your SDK.

Handle both rejected SDK calls and tool results with isError: true. Tool errors include structuredContent.error.code and a message.

For stale_document, read and reconcile before you retry. For rate limits, wait for retryAfterSeconds. Limit retries.

For plan_limit_reached, check your usage in account settings. A syntax result with valid: false needs a source correction.

Choose permissions

Select only the permissions that your client needs. Each permission applies to all diagrams in your account.

MERMAID_RENDER

Validate Mermaid source. Render SVG, PNG, and PDF files.

DIAGRAMS_READ

List and read private diagrams. Download Mermaid source.

DIAGRAMS_WRITE

Create, update, and delete private diagrams. This permission does not include read access.

DIAGRAMS_SHARE

Revoke public snapshots. Add DIAGRAMS_READ to publish snapshots.

To export a saved diagram as SVG, PNG, or PDF, select both DIAGRAMS_READ and MERMAID_RENDER.

Check limits

The Free plan includes 100 saved diagrams and 200 API renders per UTC calendar month. REST and MCP share this allowance.

Validation does not use the monthly render allowance. Request and source size limits still apply. Source can contain up to 50,000 UTF-16 code units.

View your remaining allowance and reset date in account settings. There is no self-service upgrade at this time.