Stophy MCP Server

MCP Server

Use Stophy as hosted MCP tools for YouTube search, transcripts, comments, channels, playlists, suggestions, and credits.

Copy MarkdownOpen

Stophy exposes YouTube search, transcripts, comments, channels, playlists, suggestions, and credits as MCP tools.

You can connect in two ways:

• Hosted HTTP MCP: connect directly to Stophy's hosted Streamable HTTP endpoint.
• Local npm server: run @stophy/mcp locally with your API key in the environment.

Hosted HTTP MCP

Recommended: header-based auth

Connect to the base hosted MCP endpoint and pass your API key in a standard Authorization header:

https://api.stophy.dev/v1/mcp

Authorization: Bearer $STOPHY_API_KEY

This keeps your key out of the URL. Use this method whenever your MCP client can send custom request headers.

Fallback: path-based auth (compatibility only)

For MCP clients that cannot send custom headers, Stophy also accepts the API key in the URL path:

https://api.stophy.dev/v1/mcp/st_YOUR_API_KEY

This puts your API key directly in the URL, where it can leak through browser history, Referer headers, screenshots, and server, proxy, or CDN access logs. Only use path-based auth when header auth is impossible. Prefer a key reserved for this purpose and rotate it regularly.

Local npm MCP server

env STOPHY_API_KEY=st_YOUR_API_KEY npx -y @stophy/mcp

Get your API key from stophy.dev/dashboard.

Setup

Claude Desktop

Add this to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stophy": {
      "command": "npx",
      "args": ["-y", "@stophy/mcp"],
      "env": {
        "STOPHY_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you see a spawn npx ENOENT error, Node.js is not installed or not in your PATH. Install it from nodejs.org (LTS version), then fully restart Claude Desktop.

Claude Code

Recommended — hosted endpoint with header auth (if your Claude Code version supports Streamable HTTP MCP servers):

claude mcp add --transport http stophy https://api.stophy.dev/v1/mcp \
  --header "Authorization: Bearer $STOPHY_API_KEY"

Or run the local npm server, which reads STOPHY_API_KEY from the environment:

claude mcp add stophy -e STOPHY_API_KEY=your_api_key -- npx -y @stophy/mcp

Only if your client cannot pass headers, fall back to the path-auth endpoint (see the warning above — the key is exposed in the URL):

claude mcp add --transport http stophy https://api.stophy.dev/v1/mcp/st_YOUR_API_KEY

Cursor

Open Cursor Settings

Go to Features > MCP Servers

Click "+ Add new global MCP server" and paste:

Refresh the MCP server list. The Stophy tools will appear automatically in the Composer Agent.

VS Code

Add to your User Settings JSON (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Stophy API Key",
        "password": true
      }
    ],
    "servers": {
      "stophy": {
        "command": "npx",
        "args": ["-y", "@stophy/mcp"],
        "env": {
          "STOPHY_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Or add it to .vscode/mcp.json in your project to share the config with your team:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Stophy API Key",
      "password": true
    }
  ],
  "servers": {
    "stophy": {
      "command": "npx",
      "args": ["-y", "@stophy/mcp"],
      "env": {
        "STOPHY_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

Tools

Tool	What it does
stophy_search_videos	Search YouTube by keyword with filters for type, date, duration, and sort order
stophy_get_video	Get details, transcript, comments, replies, or live chat for a video URL
stophy_get_channel	Browse a channel's videos, Shorts, playlists, or about page
stophy_get_playlist	Fetch videos in a playlist with metadata
stophy_get_suggestions	Get autocomplete suggestions for a partial query
stophy_get_credits	Check your remaining credit balance

Each tool call costs one credit. stophy_get_credits is free.

What changed on the hosted server

The hosted Stophy API now includes a Streamable HTTP MCP route at /v1/mcp.

• Tool execution uses the same credit metering, refunds, request logging, and normalized response shapes as the REST API.
• The REST API and MCP tools now share the same validation schemas, so accepted parameters stay aligned across both surfaces.
• Path-based MCP auth is supported for clients that cannot send Authorization headers.
• Concurrency limiting keys hosted MCP path-auth requests by API key instead of grouping them under a shared IP bucket.

Environment variables

Variable	Required	Description
STOPHY_API_KEY	Yes	Your Stophy API key from stophy.dev/dashboard

Error Handling

All errors return a JSON body with a machine-readable code. Concurrency limits scale with your plan.

CLI

Use Stophy from the terminal for YouTube search, transcripts, comments, channels, and playlists.