Docs · AI assistants
Connect an AI assistant
Let Claude or another assistant read your bands and add drafts, contacts and expenses — as you, with the access you choose.
What this is
Band Social speaks MCP (the Model Context Protocol), so an AI assistant such as Claude can look at your bands and, if you allow it, add to them: ask “which venues in Portugal have I not contacted yet?”, “what did the last tour cost?” or “draft three captions for the album announcement”, and it works from your real data.
The assistant acts as you. It sees only the bands you belong to and only the modules each band is currently subscribed to. It works with the Social, Booking and Pro plans and during the free trial, and it never sees another band's data.
Create an API key
- Open Account settings and find API keys.
- Choose New key, give it a name you will recognise (“Claude on my laptop”), and pick the access: Read only, or Read & write. Start with read only if you are unsure.
- Pick how long it lasts: 30 days, 90 days (recommended) or a year.
- Copy the key straight away. It starts with
bsk_and is shown once; we keep only a fingerprint, so a lost key cannot be looked up. Make a new one instead.
You can hold up to ten active keys, for example one per device. Revoke a key from the same list and it stops working immediately. Treat a key like a password: anyone who has it can do what you can, up to the access you gave it.
Connect your assistant
The server is a remote MCP server using Streamable HTTP, and it authenticates with your key in a standard Authorization header.
Claude Code — run this in a terminal, with your own key:
claude mcp add --transport http band-social https://band.social/api/mcp \
--header "Authorization: Bearer bsk_your_key_here"Any other assistant that supports remote MCP servers with custom headers: add a server with the URL https://band.social/api/mcp and the header Authorization: Bearer bsk_your_key_here. Assistants that only support servers running on your own computer, or that need a browser sign-in, cannot connect yet.
Then ask it something simple, like “list my bands”. It starts with list_bands, which shows what it can use in each one.
What it can read and change
Reading works with either kind of key:
| Tool | What it does | Needs |
|---|---|---|
list_bands | Your bands, your role, the modules usable now, and whether each is active, on trial or locked. | Any key |
list_posts, get_post | Drafts, scheduled and published posts, and one post in full with each platform’s result. | Social |
list_campaigns | Release and merch campaigns with their post counts. | Social |
get_growth | The growth check-in: cadence, content mix, calls to action, follower trend. | Social |
get_analytics_summary | Visits to your public band page over 30 days. Owners and admins only. | Social |
list_events | Your calendar: shows, festivals, releases, rehearsals. | Either module |
list_venues, list_labels, list_media_contacts | Your booking directory: venues and festivals, labels, and press contacts. | Booking |
list_tours, list_expenses, list_reminders | Tours with their stops, expenses, and follow-up reminders. | Booking |
get_booking_stats, get_booking_report | The booking dashboard counts and the financial report (fees, merch, expenses, net). | Booking |
Changing needs a Read & write key and you must be the band's owner or an admin:
| Tool | What it does | Needs |
|---|---|---|
create_draft_post | Saves a caption as a draft. You open it in the composer, add media and schedule it. | Social |
create_venue, update_venue | Adds or edits a venue or festival. Coordinates are looked up from the address. | Booking |
create_media_contact | Adds a radio, magazine, podcast, blog or other press contact. | Booking |
log_contact_event | Logs an interaction with a venue, label or press contact. It records history only. | Booking |
add_expense | Records an expense in EUR, optionally against a show. | Booking |
create_reminder | Adds a follow-up reminder on a venue or festival. | Booking |
What it can never do.
- Publish or schedule a post. Posts from an assistant are always drafts, with no media.
- Send email or message anyone. Logging an interaction only records it.
- Delete anything.
- Touch billing, your account, your connected social accounts, or the band's members.
- See a band you are not in, or a module the band is not subscribed to.
Access, limits and privacy
- Checked on every request. A key holds no permissions of its own. Each call looks up your bands and their subscriptions at that moment, so leaving a band, a trial ending or a lapsed subscription takes effect on the next request. When a band is subscribed again, everything is back.
- Limits. Up to 120 requests a minute per key, and up to 30 changes a minute. Lists come back in pages of 25 (at most 100) and very long notes are cut short.
- What we keep. For safety we log which tool a key used, on which band and whether it worked — never the captions, notes or contact details themselves. The key list shows when each key was last used.
- Your assistant sees what it reads. Whatever it reads from your bands goes to the AI provider you chose, under that provider's terms. Give it read-only access if you do not want it to change anything, and revoke the key when you stop using it.
When something goes wrong
These are the messages your assistant may relay, and what to do about each:
| You see | What it means |
|---|---|
401 Unauthorized | The key is missing, wrong, revoked or expired. Create a new one under Account settings → API keys. |
module_not_entitled | The band has no active subscription or trial for that module. Resubscribe in Band Social; your data is kept and comes straight back. |
band_not_found | You are not in that band, or it does not exist. Call list_bands to see the ones you can use. |
write_scope_required | The key is read-only. Create a Read & write key to change anything. |
role_not_permitted | Changing data, and the page analytics report, are for a band’s owner or admins. |
rate_limited | Too many changes too quickly. Wait a few seconds. |
limit_reached | The band already has the maximum number of drafts (500). |
Still stuck? Write to support@band.social and mention the time and the tool. Plans and billing are explained on the General page.