Model Context Protocol (MCP)

Getting Started

The Audioscrape MCP server is available at mcp.audioscrape.com.

Our MCP implementation supports OAuth 2.1 authentication with mandatory PKCE, dynamic client registration, and resource indicators, following the MCP Authorization spec (Nov 2025).

Pick Your Client

Step-by-step setup guides for the most common MCP clients:

Using a different MCP-compatible client? Point it at https://mcp.audioscrape.com — OAuth is handled automatically.

Available Tools

The server exposes 15 tools. Call tools/list for the authoritative, always-current schemas. All read tools are side-effect free; the only write tool is transcribe_audio (submits audio into your workspace).

Id arguments accept a JSON string or number. Legacy tool names (search_audio_content, get_episode_content, list_recent_episodes, browse_podcast, search_persons, get_person_details) remain accepted as aliases.

Detailed reference for the four most-used tools:

search_audio (alias: search_audio_content)

Search across all indexed audio content including podcasts, interviews, and talks. Find discussions on any topic with speaker identification and timestamps. Matches and result counts reflect the spoken transcript text only — episode/show metadata influences ranking but never turns a non-match into a hit.

{
  "query": {
    "type": "string",
    "description": "Search query text",
    "required": true
  },
  "search_type": {
    "type": "string",
    "enum": ["text", "semantic"],
    "default": "text",
    "description": "Type of search: 'text' for keyword matching, 'semantic' for conceptual search"
  },
  "limit": {
    "type": "integer",
    "default": 50,
    "minimum": 1,
    "maximum": 200,
    "description": "Maximum number of results"
  },
  "offset": {
    "type": "integer",
    "default": 0,
    "description": "Offset for pagination"
  },
  "sort_by": {
    "type": "string",
    "enum": ["relevance", "date", "episode_title"],
    "default": "relevance"
  },
  "sort_order": {
    "type": "string",
    "enum": ["asc", "desc"],
    "default": "desc"
  },
  "filters": {
    "type": "object",
    "properties": {
      "podcast_ids": {"type": "array", "items": {"type": "string"}},
      "date_from": {"type": "string", "description": "YYYY-MM-DD"},
      "date_to": {"type": "string", "description": "YYYY-MM-DD"},
      "recency": {"type": "string", "enum": ["last_week", "last_month", "last_year"]}
    }
  },
  "include_context": {
    "type": "boolean",
    "default": false,
    "description": "Include surrounding segments for context"
  }
}

{
  "query": "artificial intelligence ethics",
  "search_type": "semantic",
  "limit": 10,
  "filters": {
    "recency": "last_month"
  }
}

{
  "query_info": { "query": "artificial intelligence ethics", "search_type": "semantic", "total_results": 247 },
  "results": [
    {
      "id": "12345_932.5",
      "text": "The ethics of artificial intelligence is...",
      "highlighted_text": "The <mark>ethics</mark> of <mark>artificial intelligence</mark> is...",
      "timestamp_range": { "start": 932.5, "end": 958.1 },
      "speaker": "Dr. Jane Smith",
      "relevance_score": 0.95,
      "episode": { "id": "12345", "title": "The Future of AI Ethics", "publish_date": "2026-05-15T08:00:00+00:00", "description": "..." },
      "podcast": { "id": "42", "title": "Tech Talk Daily", "slug": "tech-talk-daily", "image_url": "..." },
      "source": { "type": "podcast_episode", "url": "https://www.audioscrape.com/podcast/tech-talk-daily/episode/ai-ethics?t=932.5" },
      "context": null
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_next": true, "has_previous": false },
  "has_more": true
}

list_recent_transcripts (alias: list_recent_episodes)

List recent podcast episodes with optional filtering by podcast or time period.

{
  "limit": {
    "type": "integer",
    "default": 20,
    "minimum": 1,
    "maximum": 100,
    "description": "Maximum number of episodes"
  },
  "podcast_ids": {
    "type": "array",
    "items": {"type": "string"},
    "description": "Filter by specific podcast IDs"
  },
  "days_back": {
    "type": "integer",
    "default": 7,
    "minimum": 1,
    "maximum": 365,
    "description": "Number of days to look back"
  }
}

{
  "limit": 10,
  "days_back": 3
}

{
  "episodes": [
    {
      "id": "12345",
      "title": "Latest Tech News Roundup",
      "podcast_title": "Tech Talk Daily",
      "publish_date": "2024-12-15",
      "duration_seconds": 3600,
      "url": "https://www.audioscrape.com/episode/tech-talk/news-roundup"
    }
  ],
  "total": 10
}

get_transcript (alias: get_episode_content)

Get full content and metadata for a specific episode, including transcript and speaker information. Long episodes are paged to stay under client response limits: every response carries a coverage object (first key) stating the covered time range; while coverage.truncated is true, call again with start_time = coverage.next_start_time. A 3-hour episode is typically 3–5 calls. For summaries, call get_episode_overview first instead.

{
  "episode_id": {
    "type": "string",
    "required": true,
    "description": "Episode ID to retrieve"
  },
  "start_time": {
    "type": "number",
    "default": 0,
    "description": "Resume point in seconds — pass coverage.next_start_time to page"
  },
  "max_chars": {
    "type": "integer",
    "default": 250000,
    "description": "Approx. response budget in bytes (max 400000)"
  },
  "include_segments": {
    "type": "boolean",
    "default": true,
    "description": "Include full transcript segments"
  },
  "include_metadata": {
    "type": "boolean",
    "default": true,
    "description": "Include metadata (speakers, entities)"
  }
}

{
  "episode_id": "12345",
  "start_time": 0,
  "include_segments": true,
  "include_metadata": true
}

{
  "coverage": {
    "start_time": 0, "end_time": 3385.6,
    "total_duration_seconds": 10527,
    "truncated": true, "next_start_time": 3385.7,
    "note": "PAGINATED RESPONSE — the full episode IS transcribed. ..."
  },
  "episode": {
    "id": "12345",
    "title": "The Future of AI Ethics",
    "podcast_title": "Tech Talk Daily",
    "publish_date": "2024-12-15",
    "duration_seconds": 3600,
    "description": "A deep dive into AI ethics..."
  },
  "segments": [
    {
      "start_time": "00:00:00",
      "end_time": "00:02:30",
      "text": "Welcome to Tech Talk Daily...",
      "speaker": "Host"
    },
    {
      "start_time": "00:02:30",
      "end_time": "00:05:00",
      "text": "Thank you for having me...",
      "speaker": "Dr. Jane Smith"
    }
  ],
  "speakers": ["Host", "Dr. Jane Smith"],
  "entities": [
    {"name": "Artificial Intelligence", "type": "technology"},
    {"name": "OpenAI", "type": "organization"}
  ]
}

list_podcast_episodes (alias: browse_podcast)

Browse episodes from a specific podcast series.

{
  "podcast_id": {
    "type": "string",
    "required": true,
    "description": "Podcast ID to browse"
  },
  "limit": {
    "type": "integer",
    "default": 50,
    "minimum": 1,
    "maximum": 200
  },
  "offset": {
    "type": "integer",
    "default": 0
  },
  "sort_by": {
    "type": "string",
    "enum": ["date", "title"],
    "default": "date"
  }
}

{
  "podcast_id": "tech-talk-daily",
  "limit": 20,
  "sort_by": "date"
}

{
  "podcast": {
    "id": "tech-talk-daily",
    "title": "Tech Talk Daily",
    "publisher": "Tech Media Inc",
    "description": "Daily tech news and interviews"
  },
  "episodes": [
    {
      "id": "12345",
      "title": "Latest Tech News",
      "publish_date": "2024-12-15",
      "duration_seconds": 3600
    }
  ],
  "total_episodes": 250,
  "has_more": true
}

Authentication

Two ways to authenticate, depending on your integration style:

Option A — API key (recommended for services, backends & custom connectors)

A workspace admin creates the key from the workspace's API Keys tab (open your workspace → API Keys → Create key). Send it as a Bearer token on every request to https://mcp.audioscrape.com/. No OAuth flow, no token refresh — ideal for headless/server-side integrations. The key is scoped to your workspace, so results include the public corpus plus your workspace's private audio and nothing else.

Copy-paste quickstart (JSON-RPC over HTTPS — the MCP endpoint is the root URL):

# list the tools
curl -s https://mcp.audioscrape.com/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $AUDIOSCRAPE_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# run a search
curl -s https://mcp.audioscrape.com/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $AUDIOSCRAPE_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_audio","arguments":{"query":"Sam Altman on AGI","limit":5}}}'

Verify any client interactively with the official MCP Inspector: npx @modelcontextprotocol/inspector → connect to https://mcp.audioscrape.com.

Option B — OAuth 2.1 (interactive clients: Claude, ChatGPT, Cursor…)

Spec-compliant MCP clients handle OAuth automatically (OAuth 2.1 with mandatory PKCE S256, dynamic client registration, resource indicators). For custom interactive integrations, follow this flow:

Authorization Flow

1. Discover — GET /.well-known/oauth-authorization-server
2. Register — POST /oauth/register with client_name and redirect_uris (RFC 7591)
3. Authorize — GET /oauth/authorize with code_challenge (S256) and optional resource parameter (RFC 8707)
4. Exchange — POST /oauth/token with code and code_verifier
5. Refresh — POST /oauth/token with grant_type=refresh_token (tokens are rotated)

Discovery Endpoints

• /.well-known/oauth-authorization-server — Authorization server metadata (RFC 8414)
• /.well-known/openid-configuration — Same metadata, OpenID Connect compatible
• /.well-known/oauth-protected-resource — Protected resource metadata (RFC 9728)

Example: Register a Client

POST https://mcp.audioscrape.com/oauth/register
Content-Type: application/json

{
  "client_name": "My AI App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "mcp:search mcp:read profile"
}

Manage connected apps from your profile settings.

Rate Limits

To ensure fair usage and system stability, the following rate limits apply:

• Search requests: 100 per minute
• Episode/transcript requests: 200 per minute
• List operations: 50 per minute

Example Prompts

Example queries you can ask Claude when connected:

• "Find recent discussions about artificial intelligence ethics"
• "Search for mentions of OpenAI in the last month"
• "What are podcasters saying about the latest tech trends?"
• "Get the full transcript of episode ID 12345"
• "List the latest episodes from Lex Fridman Podcast"

Troubleshooting

• It asks me to sign in — You are not signed in to audioscrape.com in that browser, or the session has expired. Sign in and you will return to the authorize screen; Google or Microsoft is a single click.
• Authentication Failed — If you signed in with an emailed link, make sure you opened it in the same browser and on the same device that started the connection, then retry from your client.
• Connection Timeout — Check your internet connection and firewall settings. The MCP server runs on port 443 (HTTPS).
• No Results Found — Try broader search terms or use semantic search for conceptual queries. Not all podcasts are indexed yet.

Support

For technical support or questions about the MCP integration, please contact us at [email protected].