> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dumplingai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DumplingAI MCP Server

> Use DumplingAI through MCP, with /mcp/v2 as the default capability-first surface and /mcp as the legacy catalog.

> ## Documentation Index
>
> Fetch the complete documentation index at: [https://docs.dumplingai.com/llms.txt](https://docs.dumplingai.com/llms.txt)
> Use this file to discover all available pages before exploring further.

# DumplingAI MCP Server

Connect Claude, Codex, Cursor, Windsurf, ChatGPT, and other MCP-compatible clients to DumplingAI.

The recommended hosted MCP server is:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

`/mcp/v2` is the default surface for new users. It uses OAuth, so most modern MCP clients only need the server URL and will handle browser sign-in automatically.

## Overview

DumplingAI currently exposes two MCP surfaces:

* `/mcp/v2`: the recommended capability-first surface backed by the Unified API
* `/mcp`: the legacy v1 tool catalog that still uses API keys

Start with `/mcp/v2` unless you specifically need the older v1 catalog.

## Getting started

Add this server URL to your MCP client:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

On first connection, DumplingAI redirects you to your browser to sign in and approve access. The OAuth grant is bound to your current active DumplingAI organization.

You do not need to configure an API key for `/mcp/v2`.

## App setup

### Claude Code

Run this command:

```bash theme={null}
claude mcp add dumplingai --transport http https://mcp.dumplingai.com/mcp/v2
```

Then restart Claude Code if needed and complete the browser-based OAuth flow on first use.

### Claude Desktop

Add a new remote MCP server in Claude Desktop and use:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Claude Desktop should open the DumplingAI OAuth flow in your browser the first time you connect.

### Codex

Run this command:

```bash theme={null}
codex mcp add dumplingai --url https://mcp.dumplingai.com/mcp/v2
```

Codex will open the OAuth flow in your browser on first use.

### Cursor

Add a new MCP server in Cursor and set the URL to:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Use Cursor's remote or URL-based MCP server option if it asks for a connection type.

### Windsurf

Add a remote MCP server with this URL:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Then finish the OAuth flow in your browser when prompted.

### VS Code / Copilot

Add DumplingAI to your MCP settings:

```json theme={null}
{
  "servers": {
    "dumplingai": {
      "type": "http",
      "url": "https://mcp.dumplingai.com/mcp/v2"
    }
  }
}
```

### ChatGPT

Add a connector or MCP server using:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Then complete the DumplingAI OAuth flow when ChatGPT prompts you.

### Other MCP clients

Any MCP client that supports hosted HTTP servers and OAuth discovery should work with:

```text theme={null}
https://mcp.dumplingai.com/mcp/v2
```

Clients discover the auth flow automatically through DumplingAI's MCP OAuth metadata.

## Authentication

`/mcp/v2` uses OAuth. That means:

* you add the server URL only
* DumplingAI handles sign-in and consent in the browser
* you do not send `Authorization: Bearer YOUR_API_KEY` for `/mcp/v2`

If your client does not support MCP OAuth yet, use the legacy `/mcp` endpoint instead.

## Available tools

`/mcp/v2` exposes these capability-first tools:

| Tool                     | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| `google_search`          | Search the web through DumplingAI's Unified API                                |
| `search_news`            | Find current headlines and recent news results                                 |
| `search_places`          | Search local businesses and Google Maps-style place results                    |
| `get_google_reviews`     | Fetch Google business reviews and reputation data                              |
| `crawl_site`             | Crawl a site and return normalized page results                                |
| `screenshot`             | Capture a page screenshot with optional wait, viewport, and full-page controls |
| `extract_web`            | Extract schema-shaped JSON from a webpage                                      |
| `extract_document`       | Extract text or structured data from one or more files                         |
| `extract_image`          | Extract text or structured data from one or more images                        |
| `extract_audio`          | Extract summaries or structured data from an audio file                        |
| `extract_video`          | Extract summaries or structured data from a video file                         |
| `scrape_page`            | Fetch and structure page content                                               |
| `get_youtube_transcript` | Get YouTube transcripts with optional timestamps                               |

Provider notes:

* `screenshot` supports `firecrawl`, `scrapingfish`, and `phantomjscloud`
* `extract_web`, `extract_document`, `extract_image`, `extract_audio`, and `extract_video` are DumplingAI-managed and surface `provider: "dumplingai"`

Example tool calls:

```json theme={null}
{
  "name": "search_news",
  "arguments": {
    "query": "latest AI news",
    "provider": "serper"
  }
}
```

```json theme={null}
{
  "name": "screenshot",
  "arguments": {
    "url": "https://example.com",
    "provider": "firecrawl",
    "fullPage": true,
    "wait": 1000,
    "viewport": {
      "width": 1280,
      "height": 800
    }
  }
}
```

```json theme={null}
{
  "name": "extract_document",
  "arguments": {
    "inputMethod": "url",
    "files": ["https://example.com/invoice.pdf"],
    "prompt": "Extract the invoice number and total amount",
    "provider": "dumplingai"
  }
}
```

```json theme={null}
{
  "name": "get_youtube_transcript",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "includeTimestamps": true,
    "provider": "transcriptapi"
  }
}
```

## Troubleshooting

### Browser flow lands on the app instead of consent

If sign-in finishes but you land on the normal app instead of returning to your MCP client, disconnect and reconnect the MCP server so the client re-runs registration and OAuth.

### `localhost` vs `127.0.0.1`

Some clients register loopback callbacks with `127.0.0.1` and then authorize with `localhost`. DumplingAI normalizes loopback redirects for supported OAuth flows, but reconnecting the client is the fastest fix if an old registration is stuck.

### OAuth is not supported in my MCP client

Use the legacy API-key surface instead:

```text theme={null}
https://mcp.dumplingai.com/mcp
```

## Legacy `/mcp` fallback

Use the legacy endpoint only if your MCP client does not support OAuth yet or if you specifically need the broader v1 tool catalog.

The hosted legacy endpoint is:

```text theme={null}
https://mcp.dumplingai.com/mcp
```

Add it with an API key header:

```json theme={null}
{
  "mcpServers": {
    "DumplingAI": {
      "url": "https://mcp.dumplingai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Get your API key from [app.dumplingai.com](https://app.dumplingai.com).

### n8n

1. Add an **AI Agent** node to your workflow.
2. Add an **MCP Client Tool** node.
3. Create MCP credentials with:
   * **Connection Type**: HTTP Streamable
   * **URL**: `https://mcp.dumplingai.com/mcp`
   * **Authentication**: Header Auth
   * **Header Name**: `Authorization`
   * **Header Value**: `Bearer YOUR_API_KEY`
4. Connect the MCP Client Tool to your AI Agent.

<Note>
  Replace `YOUR_API_KEY` with your DumplingAI API key from [app.dumplingai.com](https://app.dumplingai.com).
</Note>

***

## Legacy `/mcp` tool catalog

The rest of this page documents the older `/mcp` surface backed by `/api/v1/*`.

## Legacy Available Tools

### Web Scraping & Extraction

#### `scrape`

Fetch structured data and HTML from a URL.

```json theme={null}
{
  "name": "scrape",
  "arguments": {
    "url": "https://example.com",
    "format": "markdown",
    "clean": true,
    "render": false,
    "proxyCountry": "US",
    "includeLinks": false,
    "extractionPrompt": "Extract the main article content",
    "extractionSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "body": { "type": "string" }
      }
    }
  }
}
```

#### `crawl`

Crawl a site and return captured pages with metadata.

```json theme={null}
{
  "name": "crawl",
  "arguments": {
    "url": "https://example.com/blog",
    "limit": 50,
    "maxDepth": 3,
    "format": "markdown"
  }
}
```

#### `screenshot`

Capture a screenshot of a web page.

```json theme={null}
{
  "name": "screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true,
    "width": 1280,
    "height": 800
  }
}
```

#### `extract`

Extract structured data from a URL using AI.

```json theme={null}
{
  "name": "extract",
  "arguments": {
    "url": "https://example.com/product",
    "prompt": "Extract the product name, price, and description",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      }
    }
  }
}
```

***

### Search & Discovery

#### `search`

Perform a federated web search.

```json theme={null}
{
  "name": "search",
  "arguments": {
    "query": "latest AI news",
    "count": 5,
    "country": "US",
    "language": "en",
    "freshness": "week"
  }
}
```

#### `search_news`

Search Google News.

```json theme={null}
{
  "name": "search_news",
  "arguments": {
    "query": "electric vehicles 2025",
    "count": 10,
    "freshness": "day"
  }
}
```

#### `search_maps`

Search Google Maps.

```json theme={null}
{
  "name": "search_maps",
  "arguments": {
    "query": "coffee shops",
    "location": "San Francisco, CA"
  }
}
```

#### `search_places`

Search Google Places for businesses and points of interest.

```json theme={null}
{
  "name": "search_places",
  "arguments": {
    "query": "pizza restaurant",
    "location": "New York"
  }
}
```

#### `get_autocomplete`

Get Google search autocomplete suggestions.

```json theme={null}
{
  "name": "get_autocomplete",
  "arguments": {
    "query": "how to learn",
    "country": "US"
  }
}
```

#### `get_google_reviews`

Retrieve Google Business reviews.

```json theme={null}
{
  "name": "get_google_reviews",
  "arguments": {
    "query": "Acme Coffee San Francisco",
    "count": 20
  }
}
```

#### `google_locations`

Search for Google location metadata.

```json theme={null}
{
  "name": "google_locations",
  "arguments": {
    "query": "New York",
    "country": "US"
  }
}
```

***

### YouTube

#### `get_youtube_transcript`

Get the transcript for a YouTube video.

```json theme={null}
{
  "name": "get_youtube_transcript",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  }
}
```

#### `youtube_video`

Fetch metadata for a YouTube video.

```json theme={null}
{
  "name": "youtube_video",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}
```

#### `youtube_video_comments`

List comments for a YouTube video.

```json theme={null}
{
  "name": "youtube_video_comments",
  "arguments": {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "limit": 50,
    "sortBy": "top"
  }
}
```

#### `youtube_channel`

Fetch YouTube channel metadata.

```json theme={null}
{
  "name": "youtube_channel",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd"
  }
}
```

#### `youtube_channel_videos`

List a channel's long-form videos.

```json theme={null}
{
  "name": "youtube_channel_videos",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd",
    "limit": 20
  }
}
```

#### `youtube_channel_shorts`

List a channel's Shorts.

```json theme={null}
{
  "name": "youtube_channel_shorts",
  "arguments": {
    "channelUrl": "https://www.youtube.com/@mkbhd",
    "limit": 20
  }
}
```

#### `youtube_search`

Search YouTube.

```json theme={null}
{
  "name": "youtube_search",
  "arguments": {
    "query": "machine learning tutorial",
    "type": "video",
    "limit": 10
  }
}
```

***

### TikTok

#### `get_tiktok_profile`

Fetch a TikTok profile.

```json theme={null}
{
  "name": "get_tiktok_profile",
  "arguments": {
    "username": "@charlidamelio"
  }
}
```

#### `get_tiktok_profile_videos`

List recent videos for a TikTok profile.

```json theme={null}
{
  "name": "get_tiktok_profile_videos",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 20
  }
}
```

#### `get_tiktok_transcript`

Get the transcript for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_transcript",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890"
  }
}
```

#### `get_tiktok_video`

Fetch details for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_video",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890"
  }
}
```

#### `get_tiktok_video_comments`

Get comments for a TikTok video.

```json theme={null}
{
  "name": "get_tiktok_video_comments",
  "arguments": {
    "videoUrl": "https://www.tiktok.com/@user/video/1234567890",
    "limit": 50
  }
}
```

#### `get_tiktok_user_followers`

Get followers for a TikTok account.

```json theme={null}
{
  "name": "get_tiktok_user_followers",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 100
  }
}
```

#### `get_tiktok_user_following`

Get accounts a TikTok user follows.

```json theme={null}
{
  "name": "get_tiktok_user_following",
  "arguments": {
    "username": "@charlidamelio",
    "limit": 100
  }
}
```

#### `search_tiktok_users`

Search for TikTok users.

```json theme={null}
{
  "name": "search_tiktok_users",
  "arguments": {
    "query": "fitness influencer",
    "limit": 10
  }
}
```

***

### LinkedIn

#### `linkedin_profile`

Retrieve a LinkedIn profile.

```json theme={null}
{
  "name": "linkedin_profile",
  "arguments": {
    "profileUrl": "https://www.linkedin.com/in/satyanadella"
  }
}
```

#### `linkedin_company`

Retrieve a LinkedIn company profile.

```json theme={null}
{
  "name": "linkedin_company",
  "arguments": {
    "companyUrl": "https://www.linkedin.com/company/microsoft"
  }
}
```

***

### Document Processing

#### `doc_to_text`

Convert a PDF or DOCX to plain text.

```json theme={null}
{
  "name": "doc_to_text",
  "arguments": {
    "fileUrl": "https://example.com/report.pdf"
  }
}
```

#### `convert_to_pdf`

Convert a document or web page to PDF.

```json theme={null}
{
  "name": "convert_to_pdf",
  "arguments": {
    "url": "https://example.com/article"
  }
}
```

#### `merge_pdfs`

Merge multiple PDFs into one.

```json theme={null}
{
  "name": "merge_pdfs",
  "arguments": {
    "fileUrls": [
      "https://example.com/page1.pdf",
      "https://example.com/page2.pdf"
    ]
  }
}
```

#### `read_pdf_metadata`

Read metadata from a PDF.

```json theme={null}
{
  "name": "read_pdf_metadata",
  "arguments": {
    "fileUrl": "https://example.com/document.pdf"
  }
}
```

#### `write_pdf_metadata`

Update metadata in a PDF.

```json theme={null}
{
  "name": "write_pdf_metadata",
  "arguments": {
    "fileUrl": "https://example.com/document.pdf",
    "title": "Annual Report 2025",
    "author": "Finance Team"
  }
}
```

#### `extract_document`

Extract structured data from a document.

```json theme={null}
{
  "name": "extract_document",
  "arguments": {
    "fileUrl": "https://example.com/contract.pdf",
    "prompt": "Extract the parties, effective date, and key terms",
    "schema": {
      "type": "object",
      "properties": {
        "parties": { "type": "array", "items": { "type": "string" } },
        "effectiveDate": { "type": "string" },
        "keyTerms": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}
```

#### `extract_pdf`

Extract structured data from a PDF using AI.

```json theme={null}
{
  "name": "extract_pdf",
  "arguments": {
    "fileUrl": "https://example.com/invoice.pdf",
    "prompt": "Extract invoice number, date, and total amount"
  }
}
```

#### `extract_image`

Extract data from an image using AI vision.

```json theme={null}
{
  "name": "extract_image",
  "arguments": {
    "imageUrl": "https://example.com/chart.png",
    "prompt": "Describe the data shown in this chart"
  }
}
```

#### `extract_audio`

Extract structured data from an audio file.

```json theme={null}
{
  "name": "extract_audio",
  "arguments": {
    "fileUrl": "https://example.com/meeting.mp3",
    "prompt": "Summarize the key decisions made in this meeting"
  }
}
```

#### `extract_video`

Extract structured data from a video file.

```json theme={null}
{
  "name": "extract_video",
  "arguments": {
    "fileUrl": "https://example.com/presentation.mp4",
    "prompt": "List the main topics covered in this video"
  }
}
```

#### `trim_video`

Trim a video to a specified duration.

```json theme={null}
{
  "name": "trim_video",
  "arguments": {
    "fileUrl": "https://example.com/video.mp4",
    "startTime": 10,
    "endTime": 60
  }
}
```

***

### AI & Generation

#### `generate_agent_completion`

Build and interact with AI agents to automate complex tasks.

```json theme={null}
{
  "name": "generate_agent_completion",
  "arguments": {
    "messages": [
      { "role": "user", "content": "Research the top 5 competitors of Notion" }
    ]
  }
}
```

#### `generate_ai_image`

Generate an image from a text prompt.

```json theme={null}
{
  "name": "generate_ai_image",
  "arguments": {
    "prompt": "A futuristic city skyline at sunset, photorealistic",
    "width": 1024,
    "height": 1024
  }
}
```

***

### Developer Tools

#### `run_js_code`

Execute JavaScript in a secure sandbox.

```json theme={null}
{
  "name": "run_js_code",
  "arguments": {
    "code": "const data = [1, 2, 3, 4, 5];\nconst sum = data.reduce((a, b) => a + b, 0);\nconsole.log('Sum:', sum);"
  }
}
```

#### `run_python_code`

Execute Python in a secure sandbox.

```json theme={null}
{
  "name": "run_python_code",
  "arguments": {
    "code": "import statistics\ndata = [1, 2, 3, 4, 5]\nprint('Mean:', statistics.mean(data))\nprint('Stdev:', statistics.stdev(data))"
  }
}
```

***

## Authentication

All tool calls require a DumplingAI API key. Pass it as a Bearer token in the `Authorization` header when configuring your MCP client.

Discovery operations (`tools/list`, `initialize`) work without authentication so clients can enumerate tools before connecting.

## Error Handling

When a tool call fails, the response includes `"isError": true` and the body contains the error detail from the DumplingAI API:

```json theme={null}
{
  "content": [{ "type": "text", "text": "{\"error\": \"Insufficient credits\"}" }],
  "isError": true
}
```

Common errors:

| Status | Meaning                    |
| ------ | -------------------------- |
| 401    | Invalid or missing API key |
| 402    | Insufficient credits       |
| 429    | Rate limit exceeded        |
| 5xx    | DumplingAI API error       |

## Credit Usage

Each tool call consumes credits. Check your balance and usage in the [DumplingAI dashboard](https://app.dumplingai.com). See the [credit costs reference](/api-reference/credit-costs) for per-tool pricing.

## Support

Need help? Contact us at [help@dumplingai.com](mailto:help@dumplingai.com)