MCP Integration Guide

Overview

The Echosaw remote MCP server at https://mcp.echosaw.com allows AI assistants and developer tools to interact with Echosaw’s media intelligence capabilities directly. It uses Streamable HTTP transport with OAuth 2.0 authentication — no local installation or API keys required. Submit media URLs for analysis, retrieve results, and download source files — all from within your AI-powered development environment.

What is MCP?

The Model Context Protocol is an open standard that enables AI models and developer tools to securely connect to external data sources and services. Echosaw’s remote MCP server exposes the same capabilities as the REST API in a format optimized for AI assistant consumption.

Quick Start (Remote Server)

No installation required. Add the Echosaw MCP server URL to your MCP client configuration:

{
  "mcpServers": {
    "echosaw": {
      "url": "https://mcp.echosaw.com"
    }
  }
}

OAuth 2.0 authentication is handled automatically by your MCP client. When you first connect, your client will open a browser window for you to sign in with your Echosaw account.

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "echosaw": {
      "url": "https://mcp.echosaw.com"
    }
  }
}

Claude Desktop supports OAuth 2.0 natively — it will prompt you to sign in when you first use an Echosaw tool.

Cursor Configuration

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "echosaw": {
      "url": "https://mcp.echosaw.com"
    }
  }
}

Compatibility: mcp-remote Bridge

The configurations above use the native Streamable HTTP transport ("url" key), which requires your MCP client to support Streamable HTTP and OAuth 2.0 natively. If your client does not yet support these features, you can use the mcp-remote npm package as a bridge. It proxies the remote server through a local stdio transport and handles the OAuth flow for you.

{
  "mcpServers": {
    "echosaw": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.echosaw.com",
        "3334",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}

The 3334 argument specifies the local port for the OAuth callback, and --host 127.0.0.1 binds the callback listener to localhost. On first connection, mcp-remote will open your browser for sign-in and cache the token for subsequent sessions.

You can add "--debug" to the args array for verbose logging while troubleshooting connection issues.

Available Tools

Example Workflow

1. Submit a URL: “Analyze the video at https://example.com/interview.mp4” — calls echosaw_analyze_media_url, returns a mediaId.
2. Check status: “What’s the status of that analysis?” — calls echosaw_check_job_status.
3. Get results: “Show me the results” — calls echosaw_get_analysis_results for the full intelligence report.
4. Download source media: “Get me a download link” — calls echosaw_download_media for a presigned URL.
5. Search your library: “Find all media about product launches” — calls echosaw_search_media.
6. Ask a question: “What did the speaker say about pricing?” — calls echosaw_ask_media for an answer grounded in your media.
7. Browse your library: “What media do I have?” — calls echosaw_list_media.
8. Check your account: “What plan am I on?” — calls echosaw_get_profile.
9. Check your organization: “Show me my team” — calls echosaw_get_organization.
10. Manage folders: “Create a folder called Marketing” / “Move that video to Marketing” — calls folder management tools.
11. Publish to the Public Library: “Publish that to the Public Library” / “Make this private” — calls echosaw_set_media_visibility.

Response Format

All tools return a standardized JSON response envelope:

Local Server (Deprecated)

Note: The local stdio MCP server is deprecated and will be removed in a future release. Use the remote server at https://mcp.echosaw.com instead.

Installation

npm install -g @echosaw/mcp-server

Requires Node.js 18+ and an Echosaw API key.

Environment Variables

Local Configuration

{
  "mcpServers": {
    "echosaw": {
      "command": "echosaw-mcp",
      "env": {
        "ECHOSAW_API_KEY": "your-api-key"
      }
    }
  }
}

The local server includes an additional tool (echosaw_analyze_media) for uploading local files directly.

npm package: @echosaw/mcp-server

See Also

• REST API Reference — Direct HTTP endpoint documentation
• API Terms — Terms governing API and MCP usage