soundcloud-mcp: Instructions file for Claude Code

Agent guide

See README.md for setup and GitHub issues for open work. Issue #2 holds the dated API coverage gap list.

Layout

One pnpm package supports Node 22.18+ or 24.11+ LTS. Use package.json for exact engine and dependency versions.

• Shared: src/{client,tools,types,server,icon}.ts. Keep this code runtime-neutral: no Node or Workers APIs. Put tool changes here so both servers receive them.
• Local: src/index.ts and src/stdio/. Build first; clients run build/index.js, not TypeScript.
• Remote: src/worker.ts and src/worker/.

Node and Workers need separate typechecks because their fetch and Request types differ. pnpm typecheck runs both. Keep worker paths excluded from tsconfig.build.json: exclude replaces the base value rather than extending it. Relative imports need .js extensions for NodeNext; Wrangler resolves them to TS. Keep global fetch bound to globalThis for Workers.

API rules

Use sources in this order: the OpenAPI spec (openapi/api.yaml), SoundCloud's Agents.md in that repo, then the API guide.

Use the soundcloud-api-sync skill before adding endpoints, when these rules conflict with observed behavior, or when asked about upstream changes. Check the spec, not memory: endpoints have disappeared without notice and return 405. After auditing, update the synced-through date in the skill's SKILL.md and the gap list in issue #2. Do not copy patterns from the unmaintained official Ruby, Python, or JavaScript SDKs.

• API host: https://api.soundcloud.com. OAuth /authorize and /oauth/token: https://secure.soundcloud.com. Legacy api.soundcloud.com/oauth2/token is deprecated.
• Send Authorization: OAuth <token>, not Bearer.
• Normalize numeric IDs to URNs at the client boundary. Numeric path IDs are deprecated.
• Refresh tokens are single-use. Persist each replacement or the user must authorize again. Only one component may refresh a token.
• The worker's sole refresh owner is tokenExchangeCallback in worker.ts. Write rotated tokens back to the OAuth grant so future sessions receive them. Never refresh inside the /mcp handler; it only reads the props that OAuthProvider decrypts into ctx.props for each request.
• OAuth 2.1 requires PKCE. Preserve the verifier across redirects; the worker stores it in KV under the OAuth state token.
• Cache client-credentials tokens: limits are 50 per 12 hours per app and 30 per hour per IP. Never mint one per request.
• Pagination uses linked_partitioning=true and absolute next_href URLs. Fetch those URLs as supplied, without rebasing. Default page size is 50; maximum is 200.
• Playlist writes replace the entire tracklist. To append, read, concatenate, then PUT. Send track IDs above int32 (2147483647) as URN strings to avoid 422.
• Track access is playable, preview, or blocked. Blocked tracks have no stream. /tracks/{urn}/streams returns expiring HLS URLs plus an MP3 preview; the progressive http_mp3_128_url and /stream are gone.