@totalaudiopromo/tap-mcp

MCP server for Total Audio Promo — the music PR platform that AI agents can fully operate.

Exposes 49 tools and 3 resources via the Model Context Protocol, giving Claude, Cursor, Hermes, and custom agents access to the full music PR workflow: contacts, campaigns, drafting, outcomes, skills, approvals, batch operations, and the per-message human-gate doctrine.

What's new in 0.3.0

• Audit & Security Fixes — fail-closed cron auth, SSRF guards on coverage metadata fetch, and bounded Gmail dedup fetches to prevent duplicate sends.

What's new in 0.2.0

• REST v1 scoped-key auth is now the recommended path. Mint a key at /settings/api-keys and set TAP_API_KEY=tap_ak_…. The server proxies every read and write through https://totalaudiopromo.com/api/v1/* with that key — no Supabase credentials in your environment.
• Skill tools — tap_list_skills, tap_get_skill, tap_run_skill, tap_fork_skill, tap_get_invocation. Surfaces the workspace's editable skill set so external agents can discover what TAP can do, run a skill, and read the audit log.
• Read-only approval queue — tap_get_approval_queue. There is deliberately no tap_approve_pitch or tap_send_pitch. Approval and send are per-message human actions in the TAP UI (PRODUCT_GUARDRAILS.md §1).
• Service-role Supabase auth is deprecated. Still works for a 30-day window; will be removed after 14 June 2026. A stderr banner prints once at startup if you're still on the legacy path.

Tools

Campaign management

• tap_list_campaigns — List campaigns with optional status filter
• tap_get_campaign — Campaign detail with contact counts and pitch stats
• tap_create_campaign — Create a new draft campaign
• tap_campaign_memory — Read or write campaign learnings

Contacts

• tap_list_contacts — List contacts with filters (status, genre, BBC-only, search)
• tap_search_contacts — Free-text contact search
• tap_contact_insights — Enrichment and relationship insights
• tap_create_contact — Create a single contact
• tap_suggest_contacts — AI-scored contact suggestions for a campaign
• tap_add_contact_to_campaign — Link an existing contact to a campaign

Pitches

• tap_draft_pitch — Generate an AI draft for a single contact
• tap_list_pitch_drafts — List pitch drafts for a campaign
• tap_batch_draft_pitches — Generate drafts for up to 20 contacts at once
• tap_queue_pitch_review — Move drafts into queued-for-review state

Outcomes

• tap_log_outcome — Log campaign outcomes (replied, coverage, playlist, pass)
• tap_get_outcomes — Read outcomes for a campaign
• tap_get_channel_outcomes — Group outcomes by channel

Skills (new in 0.2.0)

• tap_list_skills — Discover the workspace's skill set (defaults + forks)
• tap_get_skill — Fetch a skill in full (manifest, body, source)
• tap_run_skill — Execute a skill; writes a skill_invocation audit row
• tap_fork_skill — Override a default skill body with the workspace's edit
• tap_get_invocation — Read a single audit row by id

Approvals (new in 0.2.0)

• tap_get_approval_queue — Read-only view of pitches awaiting human review
• tap_request_approval — Pause an agent session and wait for human review
• tap_get_approval_status — Poll an agent_sessions row for an approval verdict

Analysis

• tap_analyse_campaign — Performance, outcomes, and relationship metrics in one call
• tap_get_action_queue — Today's prioritised action queue

Batch operations

• tap_batch_enrich — Queue enrichment for multiple contacts
• tap_batch_import — Import contacts in bulk with dedupe + validation
• tap_batch_validate — Validate multiple contact records
• tap_batch_draft_pitches — see Pitches

Assets, monitoring, consent

• tap_get_asset_url — Resolve a workspace asset to a signed download URL
• tap_list_campaign_assets — List assets attached to a campaign
• tap_get_play_summary — WARM summary for a campaign (radio detections)
• tap_list_radio_plays — Per-station play history
• tap_enrol_reference_track — Add a track to the fingerprint monitor
• tap_set_send_consent — Toggle workspace-level send consent

Outreach + sequences

• tap_create_sequence — Build a multi-step outreach sequence
• tap_propose_send — Surface a draft into the human approval queue
• tap_queue_execution / tap_approve_execution / tap_list_pending_executions — Sequence execution gate

Resources

• tap://campaigns — Browse campaigns as JSON
• tap://contacts — Browse contacts as JSON
• tap://artists — Browse artists as JSON

Setup

Recommended: REST v1 with a scoped API key

1. Sign in to your workspace at https://totalaudiopromo.com.
2. Go to Settings → API Keys (Agency tier).
3. Mint a new key with the scopes you need. For a full agent: contacts:read contacts:write campaigns:read campaigns:write pitches:read pitches:write outcomes:read outcomes:write approvals:read skills:read skills:write webhooks:read webhooks:write enrich validate. For a read-only audit agent: just the :read scopes.
4. Note your workspace id (visible in the URL after /workspace/).
5. Configure your MCP client:

{
  "mcpServers": {
    "tap": {
      "command": "npx",
      "args": ["-y", "@totalaudiopromo/tap-mcp@latest"],
      "env": {
        "TAP_API_KEY": "tap_ak_abc123...",
        "TAP_WORKSPACE_ID": "0544294f-..."
      }
    }
  }
}

That's it. The server proxies every call through /api/v1/* with your key. Rotating the key is a single click in the UI; the server picks up the new value on next restart.

Legacy: service-role Supabase (deprecated, removed 14 June 2026)

{
  "mcpServers": {
    "tap": {
      "command": "npx",
      "args": ["-y", "@totalaudiopromo/tap-mcp@latest"],
      "env": {
        "TAP_SUPABASE_URL": "https://...supabase.co",
        "TAP_SUPABASE_KEY": "eyJ...",
        "TAP_WORKSPACE_ID": "0544294f-..."
      }
    }
  }
}

On startup the server prints a one-time stderr warning. Migrate before 14 June 2026.

Guardrails (the parts that don't move)

• Agents draft, humans send. No tool in this server moves a pitch past approved. tap_get_approval_queue is read-only. tap_propose_send enters the queue; nothing exits it without a human.
• Workspace scope on every call. Every tool resolves the workspace from the API key (REST mode) or TAP_WORKSPACE_ID (legacy). Cross-workspace reads are impossible.
• Rate limits. 10 req/minute/key on v1 endpoints — surfaced via X-RateLimit-* headers. Mint a separate key per agent if you need higher throughput on one call type.
• Audit log. Every skill invocation writes to skill_invocation. Every send signal writes to tap_signals with source_app: 'mcp' so the workspace's Co-pilot → History tab shows exactly what each agent did.

Working with skills

tap_list_skills returns the skills available in the calling workspace. TAP ships sensible defaults; Agency-tier workspaces can fork any default and edit it through the UI (/settings/skills) or via tap_fork_skill.

> tap_list_skills
{
  "skills": [
    { "slug": "draft-pitches",     "source": "default",   "version": "1.0.0" },
    { "slug": "fact-check",        "source": "default",   "version": "1.0.0" },
    { "slug": "voice-check",       "source": "workspace", "version": "1.2.0" },
    { "slug": "cross-check-contacts", "source": "default", "version": "1.0.0" }
  ]
}

Running a skill records the input/output/error/duration in skill_invocation and (for programmatic skills) returns the structured output inline. For llm skills the output may include a draft payload — that draft goes into campaign_pitch_drafts with approval_state: 'pending' and waits for human approval.

> tap_run_skill --slug draft-pitches --input '{"campaign_id":"...","contact_ids":["..."]}'
{
  "ok": true,
  "invocation_id": "a3...",
  "output": { "drafts_created": 12, "queued_for_approval": 12 },
  "duration_ms": 4200
}

Environment variables

| Variable | Required (REST) | Required (legacy) | Purpose | | ----------------------- | --------------- | ----------------- | --------------------------------------------------------- | | TAP_API_KEY | yes | no | tap_ak_* scoped key from /settings/api-keys | | TAP_WORKSPACE_ID | yes | yes | Workspace UUID — defence in depth | | TAP_URL | no | no | Override base URL (default https://totalaudiopromo.com) | | TAP_SUPABASE_URL | no | yes | Supabase project URL (legacy only) | | TAP_SUPABASE_KEY | no | yes | Supabase service-role key (legacy only) | | TAP_SUPABASE_ANON_KEY | no | optional | Anon key for RLS-scoped client (legacy only) | | TAP_ACCESS_TOKEN | no | optional | User access token (legacy only) | | TAP_CRON_SECRET | optional | optional | Required for tap_batch_draft_pitches legacy path |

Related

• REST API v1 spec: https://totalaudiopromo.com/.well-known/api-catalog
• OpenAPI: https://totalaudiopromo.com/api/openapi.json
• Agent skills index (public): https://totalaudiopromo.com/.well-known/agent-skills/index.json
• Agent skills index (workspace, auth): GET /.well-known/agent-skills/workspace/index.json with Authorization: Bearer tap_ak_…
• Sibling tools: tap-cli (terminal), sink-cli (contact discovery)
• Developer docs: https://totalaudiopromo.com/developers

License

MIT. Source at https://github.com/totalaudiopromo/total-audio-platform/tree/main/packages/tap-mcp.