Integrations

Testing Over MCP

Verify a Model Context Protocol integration against the Audioscrape MCP server: OAuth discovery and client registration, the protocol handshake, tool calls, error shapes, and continuous checks. Each step has a copy-paste command and the result to expect.

This is the MCP companion to Testing Your Integration, which covers the same method over the REST API. Server fundamentals and client setup live in the MCP Overview.

Step 1

Discovery, Registration, and Tokens

Everything an MCP client needs is discoverable: no pre-shared credentials. Start where your client starts: 

curl "https://mcp.audioscrape.com/.well-known/oauth-protected-resource"
curl "https://mcp.audioscrape.com/.well-known/oauth-authorization-server"

Both must return JSON: the second advertises the authorization, token, and dynamic-registration endpoints, PKCE (S256), and the supported scopes. Register a client: 

curl -X POST "https://mcp.audioscrape.com/oauth/register" \
     -H "Content-Type: application/json" \
     -d '{"client_name": "Your MCP Client", "redirect_uris": ["https://yourapp.example/callback"]}'
{
  "client_id": "mcp_client_...",
  "client_secret": "...",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "mcp:search mcp:read"
}

The authorization step runs in a browser: your client sends the user to /oauth/authorize with a PKCE challenge, the user signs in and approves, and the code returns to your redirect URI with your state echoed. Exchange it: 

curl -X POST "https://mcp.audioscrape.com/oauth/token" \
     -d "grant_type=authorization_code&code=CODE&redirect_uri=https://yourapp.example/callback&client_id=CLIENT_ID&code_verifier=VERIFIER"
{
  "access_token": "mcp_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mcp_rt_...",
  "scope": "mcp:search mcp:read"
}

Access tokens live one hour. Test the refresh_token grant before you need it in production: long-lived connectors refresh many times a day, and a broken refresh path looks like a working integration for exactly one hour.

Step 2

Handshake and Tool Inventory

The server speaks JSON-RPC 2.0 over streamable HTTP: POST each request to the server root with your Bearer token. Two protocol notes that trip up new clients: a GET to the root returns 405 (spec-conformant for servers that do not open a server-to-client stream), and all responses come back as ordinary JSON bodies. 

curl -X POST "https://mcp.audioscrape.com/" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
          "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                     "clientInfo": {"name": "your-client", "version": "1.0"}}}'

The result carries server info and capabilities. Then list tools: 

curl -X POST "https://mcp.audioscrape.com/" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Expect the full tool inventory, each with an inputSchema and safety annotations (readOnlyHint, destructiveHint, openWorldHint). If you build agent tooling on top, read the annotations rather than assuming: two tools (transcribe_audio, create_share_link) are writes.

Step 3

Call a Read Tool

curl -X POST "https://mcp.audioscrape.com/" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
          "params": {"name": "search_audio",
                     "arguments": {"query": "a phrase from your own recording", "limit": 5}}}'
{
  "jsonrpc": "2.0", "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{ \"results\": [...], \"pagination\": {...}, \"query_info\": {...} }" }]
  }
}

The payload arrives as JSON inside content[0].text; results carry the episode, matching segment, timestamp, and speaker. As on the REST path: search a phrase you know occurs in your own audio, and confirm your item appears. Public corpus hits alone do not prove your data is indexed. Follow with get_transcript on one of your items to verify retrieval. The tool also accepts a type argument (text or semantic, plan permitting); test every mode your integration will use.

Step 4

Call the Write Path

Submit a short, publicly downloadable audio URL (a minute or two, cheap to repeat) and poll it to completion: 

curl -X POST "https://mcp.audioscrape.com/" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 4, "method": "tools/call",
          "params": {"name": "transcribe_audio",
                     "arguments": {"audio_url": "https://yourhost.example/short-test-clip.mp3",
                                   "title": "MCP integration test"}}}'

The result returns a job_id; poll get_transcription_status until it reports completed, then apply the same four pass conditions as the REST guide: completed status, more than zero segments, duration greater than zero, and at least one speaker-attributed segment (see Uploads Become Transcripts). The item should then match in search_audio and appear in list_my_uploads.

Step 5

Failure Shapes

Exercise these on purpose and confirm your client surfaces them cleanly: 

HTTP/2 401
www-authenticate: Bearer realm="MCP", resource_metadata="https://mcp.audioscrape.com/.well-known/oauth-protected-resource"

The WWW-Authenticate header points back at the discovery metadata. Well-behaved clients use it to re-enter the OAuth flow automatically. Tool-level failures come back as JSON-RPC errors, not HTTP errors: 

{"jsonrpc": "2.0", "id": 5, "error": {"code": -32603, "message": "Tool execution failed: Unknown tool: nope"}}
{"jsonrpc": "2.0", "id": 6, "error": {"code": -32603, "message": "Tool execution failed: Invalid arguments: missing field `query`"}}

Rate limiting applies per source; read the x-ratelimit-* response headers and back off on 429 rather than retrying into the limit.

Step 6

Keep It Tested

Script the round-trip you just ran: tools/list, one search_audio call asserting a known phrase matches, and a token refresh. Run it on a schedule and after every deploy of your client. Alert on failure. Token refresh belongs in the canary specifically: it is the piece that only breaks after the demo works. The general canary pattern, including growing it into a golden query set grounded in your own corpus, is covered in the REST guide.

Next

Going Further

Server fundamentals, scopes, and client setup guides: MCP Overview. The same method over REST: Testing Your Integration. Enterprise plans include isolated evaluation workspaces with seeded test data for integration certification. Ask at [email protected].

Previous
Testing Your Integration