MCP Server

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

Stophy exposes video search, transcripts, comments, channels, playlists, 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.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

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=st_YOUR_API_KEY -- npx -y @stophy/mcp

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

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:

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

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:

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

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_credits`	Check your remaining credit balance

Each tool call costs one credit. stophy_get_credits is free.

How the hosted server behaves

The hosted Stophy API serves 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 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

On this page