Using the Stagent MCP Server

Stagent provides a Model Context Protocol (MCP) server that allows AI assistants like Claude to directly access your booking data, events, artists, and analytics. This enables powerful conversational queries and insights about your agency's performance.


What is MCP?

MCP (Model Context Protocol) is a standard protocol that allows AI assistants to securely connect to external data sources. With Stagent's MCP server, you can ask natural language questions about your bookings, events, revenue, and artists directly in compatible AI tools.


Setting Up the MCP Connection


Prerequisites

  • A Stagent account with API access enabled
  • An MCP-compatible AI client (such as Claude Desktop, ChatGPT, Cursor, or other MCP clients)

Connecting to AI Clients

Setup varies depending on which AI assistant you use. See the specific guide for your client:


Manual Configuration

Add the Stagent MCP server to your AI client's configuration:

{
  "mcpServers": {
    "stagent": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.stagent.com/mcp/stagent",
        "--header",
        "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

Replace YOUR_ACCESS_TOKEN with your personal API token from Stagent.


Getting Your Access Token

  1. Go to Personal settings → API in Stagent
  2. Click Create New Token
  3. Give it a descriptive name (e.g. "Claude Desktop")
  4. Copy the token and add it to your MCP configuration

Available Tools

The Stagent MCP server provides 8 tools for querying your data:


Teams & Artists


list-teams


List all teams (artists and booking agencies) you have access to. This is typically the first tool to use to discover available team IDs.


Parameters:

  • type       - Filter by team type: artist or booking_agency
  • search      - Search by team name or company name
  • include_stats       - Include booking and revenue statistics (default: false)
  • limit      offset       - Pagination controls

Example questions:

  • "Show me all my booking agencies"
  • "Which artists had the most bookings this year?"

get-team


Get detailed information about a specific team including configuration, currency, and contact details.


Parameters:

  • team_id       (required) - The team ID to retrieve
  • include_stats       - Include year-over-year comparison statistics

Example questions:

  • "Show me details for [Agency Name]"
  • "Compare this year vs last year for [Agency]"

list-artists


List artists in a booking agency's roster with optional performance statistics.


Parameters:

  • booking_agency_id       (required) - The booking agency to list artists for
  • search       - Search by artist name
  • include_stats       - Include booking and revenue statistics per artist
  • order_by       - Sort by name, bookings_this_year, or total_artist_fee_this_year
  • limit      offset       - Pagination controls

Example questions:

  • "Show me all artists on my roster sorted by revenue"
  • "Which artists have the most bookings this year?"

Events


list-events


List events with comprehensive filtering options. Returns event details including venue, buyer, booking count, and financial information.


Parameters:

  • team_id       - Filter by team
  • status       - Filter by status: advancing, ready, completed, canceled
  • type       - Filter by event type: club, conference, corporate, festival, private, outdoor, wedding
  • time_period       - Quick filter: upcoming      past      today      this_week      this_month      next_month      
  • starts_after     starts_before       - Date range filter (YYYY-MM-DD)
  • buyer_id       - Filter by buyer/promoter
  • venue_name       - Filter by venue name (partial match)
  • country_code       - Filter by venue country (ISO code, e.g., "BE", "NL", "DE")
  • venue_city       - Filter by venue city
  • search       - Search by event name, venue name, or buyer name
  • include_cancelled       - Include cancelled events (default: false)
  • include_financial_summary       - Include aggregated totals by currency

Example questions:

  • "Show me all upcoming festival events"
  • "What events do we have in Germany this month?"
  • "List events for [Buyer Name] with financial summary"

get-event


Get detailed information about a specific event including venue, buyer, all bookings (lineup), and financial summary.


Parameters:

  • event_id       (required) - The event ID to retrieve

Example questions:

  • "Show me the full lineup for [Event Name]"
  • "What's the total revenue for [Event]?"

Bookings


list-bookings


List bookings with extensive filtering. Returns booking details including event, artist, venue, and financial information.


Parameters:

  • team_id       - Filter by team (booking agency)
  • artist_id       - Filter by artist
  • status       - Filter by status: pending, option, confirmed, cancelled, requested
  • time_period       - Quick filter: upcoming      past      today      this_week      this_month      next_month       this_year      last_year      
  • starts_after      starts_before       - Date range filter
  • buyer_id       - Filter by buyer/promoter
  • country_code       - Filter by venue country
  • venue_city       - Filter by venue city
  • event_type      - Filter by event type
  • search       - Search by artist name, event name, or venue name
  • include_cancelled       - Include cancelled bookings (default: false)
  • include_summary       - Include aggregated totals by currency

Example questions:

  • "Show me all confirmed bookings for [Artist] this year"
  • "What bookings do we have in Belgium next month?"
  • "List all headliner bookings over €5000"

get-booking


Get detailed information about a specific booking including event details, artist, buyer, venue, financial terms, exclusivity rules, and deal information.


Parameters:

  • booking_id       (required) - The booking ID to retrieve

Example questions:

  • "Show me the details for booking [ID]"
  • "What are the exclusivity terms for [Artist]'s booking at [Event]?"

Analytics


get-booking-statistics


Get comprehensive booking statistics and analytics. This is the most powerful tool for business intelligence.


Parameters:

  • team_id       - Filter by team
  • artist_id       - Filter by artist
  • time_period       - Quick filter: this_month, last_month, this_year, last_year, this_quarter, last_quarter
  • starts_after       / starts_before - Custom date range
  • group_by       - Aggregate by dimension: artist, buyer, country, event_type, month, week, status
  • country_code       - Filter by country
  • buyer_id       - Filter by buyer
  • event_type       - Filter by event type
  • status       - Filter by booking status
  • min_artist_fee       max_artist_fee       - Filter by fee range
  • time_granularity       - Add time series: day, week, month, quarter, year
  • order_by       - Sort grouped results: bookings_count, artist_fee_total, booking_fee_total
  • limit       - Limit number of grouped rows

Example questions:

  • "What's my total revenue this year by country?"
  • "Show me monthly booking trends for 2024"
  • "Which buyers generated the most revenue last quarter?"
  • "Compare festival vs club bookings this year"
  • "Who are my top 10 artists by booking count?"

Example Conversations


Revenue Analysis

"What was my total artist fee revenue this year, broken down by country?"


The AI will use get-booking-statistics       with group_by=country       and time_period=this_year       to provide a country-by-country breakdown.


Booking Pipeline

"Show me all pending and option bookings for next month"


The AI will use list-bookings       with status filter and time_period=next_month       to show your upcoming pipeline.


Artist Performance

"Which of my artists had the highest booking fees this  year?"


The AI will use list-artists       with include_stats=true       and order_by=total_artist_fee_this_year      to show you the artist's highlights.


Event Details

"Show me the full lineup and financials for Ultra Miami"


The AI will use get-event       to retrieve all bookings, artist fees, and booking fees for the event.


Data Security

  • All API requests are authenticated using your personal access token
  • The MCP server only returns data you have permission to access in Stagent
  • Data is read-only, the MCP server cannot modify your Stagent data
  • All connections use HTTPS encryption

Troubleshooting


Connection Issues

  • Verify your access token is valid and not expired
  • Check that your MCP client is configured correctly
  • Ensure you're using https:// in the server URL

No Data Returned

  • Confirm you have access to the teams you're querying
  • Check that your filters aren't too restrictive
  • Use list-teams first to verify available team IDs

SSL Certificate Errors

Some MCP clients using Node.js may have certificate issues with local development URLs. Use http:// instead of https:// for local testing.


FAQ


Can I modify data through the MCP server?

No, the Stagent MCP server is read-only. All tools are marked as safe read operations. To modify data, use the Stagent web interface or API directly.


How current is the data?

The MCP server queries your live Stagent database, so data is always current.


What currencies are supported?

Financial data is returned in the currency configured for each team. The statistics tools automatically group results by currency when multiple currencies are present.


Can I share my access token?

No. Treat your access token like a password. Each user should generate their own token. Tokens can be revoked at any time from Personal Settings → API Tokens.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us

Related Articles