> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.sessionboard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI assistants to Sessionboard via Model Context Protocol

> [!NOTE]
>
> **Early Access** — The MCP server is available to organizations with AI features enabled. Reach out to your Sessionboard account manager if you'd like it turned on.

The Sessionboard MCP (Model Context Protocol) server lets AI assistants like Claude, ChatGPT, Microsoft Copilot, and Google Gemini query and manage your event data directly. Built on the open [Model Context Protocol](https://modelcontextprotocol.io/) standard, it exposes **39 tools** covering search, reads, natural-language queries, cited answers about an event, reports and dashboards, and write operations.

This page is the technical reference. If you just want to connect an assistant, the Help Center has friendlier step-by-step guides with screenshots — start at the [AI assistants overview](https://learn.sessionboard.com/integrations/connect-ai-assistants):

* [Connect Claude](https://learn.sessionboard.com/integrations/connect-claude) — including Sessionboard's listing in Claude's connector directory
* [Connect ChatGPT](https://learn.sessionboard.com/integrations/connect-chatgpt) — via a developer-mode connector
* [Connect Microsoft Copilot](https://learn.sessionboard.com/integrations/connect-microsoft-copilot) — via a Copilot Studio agent
* [Connect Google Gemini](https://learn.sessionboard.com/integrations/connect-google-gemini) — Gemini app, Gemini Enterprise, or the Gemini CLI

## What is MCP?

Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools. Instead of copying data into prompts, MCP lets the AI query and update your data on demand through a structured interface.

## Server URLs by region

Each Sessionboard region runs its own MCP server. Use the one matching where your organization is hosted:

| Region | MCP server URL |
| - | - |
| United States | `https://mcp.sessionboard.com/mcp` |
| Europe | `https://mcp-eu.sessionboard.com/mcp` |
| Middle East | `https://mcp-me.sessionboard.com/mcp` |

The server uses the streamable HTTP transport and supports OAuth 2.0 with PKCE and dynamic client registration — most clients discover the sign-in flow automatically.

## Prerequisites

> [!WARNING]
>
> Two things must be true before the hosted MCP server will accept a sign-in:
>
> 1. **AI features are enabled for the organization.** Contact Sessionboard support or your account manager if they are not.
> 2. **The person signing in has the Connect AI assistants permission.** Organization administrators have it. Other roles need it granted in role settings.
>
> Claude, ChatGPT, Copilot, Gemini, and any other remote client connect with **OAuth**. There is no MCP switch on the organization or on an API token, and pasting an API token into the assistant will not authenticate. The hosted server (`https://mcp.sessionboard.com/mcp` and the regional hosts) accepts the OAuth bearer token from that sign-in.
>
> An API token is for scripts calling the public API with `x-access-token`. Those calls to `/v1/insights/...` need the **`read:insights`** scope (a token with an empty scope list is the legacy full-access case and can call them too). Write scopes such as `write:sessions` are separate.

## Setup

**1. Connect your AI client**

Most assistants (Claude, ChatGPT, Copilot Studio, Gemini) connect through their own UI — follow the [Help Center guides](https://learn.sessionboard.com/integrations/connect-ai-assistants) above. For clients configured by file (Claude Code, Cursor, and similar), add:

```json theme={null}
{
  "mcpServers": {
    "sessionboard": {
      "url": "https://mcp.sessionboard.com/mcp"
    }
  }
}
```

Swap in the EU or Middle East URL from the table above if that's where your organization is hosted.

**2. Sign in**

On first use the client walks you through Sessionboard's OAuth sign-in and organization consent automatically — no token to copy. A client that cannot complete that sign-in cannot use the hosted MCP URL. Scripts call the public API with an [API token](https://apidocs.sessionboard.com/authentication.md) instead.

**3. Start querying**

Ask your AI assistant questions about your event data in natural language. The assistant uses the MCP tools to query Sessionboard and return results.

## Available Tools (46)

The MCP server exposes 46 tools in five groups. Write operations use a `manage_*` pattern — one tool per entity with an `action` parameter to pick the operation (e.g., `action: "create"`).

All tools include [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) for safe AI behavior — read tools are marked `readOnlyHint: true`, every `manage_*` tool is marked `destructiveHint: true` because each can overwrite an existing record through its `update` action (even the ones with no `delete`), and all are `openWorldHint: false` because every tool is bounded to your organization's data. Clients such as Claude and ChatGPT use these hints to ask for confirmation before a write runs.

### Search & Discovery (11 tools)

Find events, search your data, ask questions in plain English, and explore your schema.

| Tool | Description |
| - | - |
| `list_events` | List all events in the organization |
| `find_event` | Search events by name |
| `get_event_overview` | Event summary — session counts, speakers, tracks, status breakdown |
| `search` | Full-text search across sessions and speakers with citation URLs |
| `fetch` | Fetch a single search result by ID (pairs with `search`) |
| `get_schema` | Browse your data model — entities, fields, and relationships |
| `query_data` | Ask a question in plain English and get results (AI writes the query for you) |
| `execute_sbql` | Run a [SbQL](https://apidocs.sessionboard.com/insights/sbql.md) query directly with pagination |
| `get_suggestions` | Get suggested queries based on your data |
| `get_widget_schema` | Widget types, configs, and grid layout rules for dashboards |
| `ask_event` | Ask a question about one event and get a cited answer — see [Asking about an event](#asking-about-an-event). Needs `read:ask` |

### Read Details (4 tools)

Fetch sessions and contacts. All read-only and paginated.

| Tool | Description |
| - | - |
| `list_sessions` | List sessions for an event (paginated, up to 100 per page) |
| `get_session` | Get a single session by ID with full details |
| `list_contacts` | List contacts for an event (paginated, up to 100 per page) |
| `get_contact` | Get a single contact by ID with full details |

### Read-Only Lists (9 tools)

Read counterparts to the `manage_*` tools — safe to call without any write scopes.

| Tool | Description |
| - | - |
| `list_metadata` | Rooms, tracks, tags, formats, levels, languages, statuses, and custom fields |
| `read_agenda_drafts` | List and inspect agenda drafts |
| `list_draft_sessions` | Session placements within a draft |
| `read_event_rules` | Scheduling rules and constraints |
| `read_personas` | Evaluation personas |
| `read_event_dashboards` | Event-scoped dashboards |
| `list_event_reports` | Event-scoped saved reports |
| `read_org_dashboards` | Org-level dashboards (cross-event) |
| `list_org_reports` | Org-level saved reports (cross-event) |

### Create & Manage (15 tools)

Each `manage_*` tool handles all operations for an entity — create, update, delete, and more — using an `action` parameter. For example, `manage_session` with `action: "create"` creates a session, while `action: "update"` updates one.

| Tool | Actions | Scope | Description |
| - | - | - | - |
| `manage_metadata` | `list`, `create`, `update` | `write:metadata` / `write:fields` | Rooms, tracks, tags, formats, levels, languages, statuses, and custom fields |
| `manage_session` | `create`, `update`, `restore`, `update_fields` | `write:sessions` | Session CRUD + custom field values |
| `manage_contact` | `create`, `update`, `restore` | `write:contacts` | Contact CRUD (find-or-create by email) |
| `manage_exhibitor` | `create`, `update`, `restore` | `write:exhibitors` | Exhibitor CRUD |
| `manage_sponsor` | `create`, `update`, `restore` | `write:sponsors` | Sponsor CRUD |
| `manage_agenda_draft` | `list`, `get`, `create`, `update`, `delete`, `get_changes`, `commit` | `write:events` | Agenda draft lifecycle |
| `manage_draft_sessions` | `list`, `create`, `update`, `delete`, `bulk` | `write:events` | Session placements in drafts |
| `manage_event_rules` | `list`, `get`, `create`, `update`, `delete` | `write:events` | Scheduling rules and constraints |
| `manage_personas` | `list`, `get`, `create`, `update`, `delete` | `write:events` | Evaluation personas |
| `manage_event_dashboard` | `list`, `get`, `create`, `update`, `delete` | `write:events` | Event-scoped dashboards |
| `manage_event_widget` | `create`, `update`, `delete` | `write:events` | Event dashboard widgets |
| `manage_event_report` | `list`, `run`, `create`, `create_from_nl`, `update`, `delete` | `write:events` | Event-scoped saved reports |
| `manage_org_dashboard` | `list`, `get`, `create`, `update`, `delete` | `write:events` | Org-level dashboards (cross-event) |
| `manage_org_widget` | `create`, `update`, `delete` | `write:events` | Org-level dashboard widgets |
| `manage_org_report` | `list`, `run`, `create`, `create_from_nl`, `update`, `delete` | `write:events` | Org-level saved reports (cross-event) |

### Registration (7 tools)

Read-only answers about an event's registration: the funnel, attendees, orders, payments, membership, capacity and setup. They need the `read:registrations` scope, which is in preview: ask Sessionboard support to add it to your token, or name it in your OAuth `scope` request. The event must have Registration turned on (Early Access); otherwise these tools say so instead of answering.

| Tool | Actions | Description |
| - | - | - |
| `read_registration_summary` | — | Registrations by status, by day, per ticket type, attendee type and form; member mix; revenue; orders per status; invoices still owed; capacity pools |
| `find_registrations` | `search`, `get` | Find attendees by a name, email or company fragment, or filter by status, ticket type, attendee type or form; one registration in full |
| `read_registration_orders` | `list`, `get` | Find an order by number or buyer email, or list orders by status (`awaiting_invoice`, `partially_paid` still owe); one order in full |
| `read_registration_payments` | `list`, `get` | Payment records: card and bank payments through your payment gateway and offline money, failed attempts with their reason, refunds and the charge they refund. Never card numbers or tokens |
| `read_registration_members` | `lookup`, `list` | Check one email the way the form does (member, lapsed or none), or list registrations with the membership recorded when they registered |
| `read_registration_capacity` | — | Every ticket type's capacity, sold and available, plus shared capacity pools |
| `read_registration_setup` | `section` | Fee groups and their promo codes, donation funds with raised and pledged totals, workshop picking rules, the badge print queue |

Try: *"How many people registered for Annual Meeting 2026 last week, and how much is still owed on invoices?"* or *"Is [ada@example.org](mailto:ada@example.org) a member, and is she registered?"*

## Asking about an event

`ask_event` answers a question about one event the way an organizer would want it answered. The answer is grounded in the event's program (sessions, speakers, exhibitors, sponsors), session transcripts, the event's knowledge and pinned answers, and the Sessionboard Help Center, and it cites its sources with `[n]` markers listed under **Sources**. It calls [`POST /v1/event/{eventId}/ask`](https://apidocs.sessionboard.com/api-reference/ask/ask-a-question-about-an-event).

| Input | Required | Description |
| - | - | - |
| `event_id` | Yes | The event to ask about |
| `question` | Yes | The question, in plain language (up to 500 characters) |
| `conversation_id` | No | The `conversation_id` from a previous answer, to ask a follow-up in the same thread |
| `lang` | No | Answer language as a language tag (e.g. `en`, `fr`, `pt-BR`) |

* **Scope** — needs `read:ask`. Assistants connected before this scope existed hold only the scopes they were granted; reconnect to grant it.
* **Read-only** — marked `readOnlyHint: true`. Ask never changes the event.
* **Use it for synthesis** — "which sessions cover X", "what did speakers say about Y", "how do I set up Z". For exact counts and lists, `execute_sbql` and `query_data` are faster and exact.
* **Slow** — an answer takes several seconds; the tool waits up to 90 seconds.
* **Follow-ups** — the answer ends with a `conversation_id`. Pass it back to continue the thread.
* **Refusals come back as tool errors** — Ask turned off for the event, AI features off, the per-user question limit (with the seconds to wait), the event's daily Ask budget used up, or a question Ask would not take.

## Parameter Conventions

* **Event scoping** — All event-scoped tools require `event_id` (snake\_case string).
* **Action selection** — Consolidated tools use `action` to pick the operation (e.g., `action: "create"`).
* **Entity IDs** — snake\_case: `session_id`, `contact_id`, `entity_id`, `draft_id`, `widget_id`, `query_id`.
* **Optimistic concurrency** — Update actions require `updated_at` (ISO 8601 timestamp from the last read). Returns `409 Conflict` if the entity was modified since.

## Result Size Safety

All results are automatically truncated to prevent context window overflow:

* **List results** — Capped at 50 items. When truncated, the response includes `truncated: true`, `total_count`, and a `hint` with guidance on pagination.
* **Query results** — Capped at 100 rows with truncation metadata.
* **SbQL queries** — `execute_sbql` and `query_data` default to a 50-row limit. Use the `limit` parameter for more.

## Resources

The MCP server also exposes two [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) that AI clients can load into context:

| URI | Description |
| - | - |
| `sbql://schema` | The SbQL schema — entities, fields, relationships, and format functions |
| `sbql://events` | List of events in the organization with metadata |

## Prompt Templates

Pre-built templates that structure the AI's approach to common report types:

| Prompt | Description |
| - | - |
| `speaker_roster` | Generate a speaker roster with contact info and session assignments |
| `session_schedule` | Generate a day-by-day session schedule grid |
| `evaluation_summary` | Generate an evaluation/review score analysis |
| `task_status` | Show outstanding tasks across speakers and exhibitors |

## Security

* **Org isolation** — The SbQL compiler injects `org_id` into every query from the authenticated token. Prompt injection cannot access other organizations' data.
* **PII masking** — OAuth connections always mask PII in query results: emails become `j***@a***.com`, phone numbers become `***-***-4567`. For API-token calls to the query routes, masking follows that token's **PII Obfuscation** setting (off by default — turn it on for any token a third party will use). See [privacy details in the Help Center](https://learn.sessionboard.com/integrations/connect-ai-assistants#privacy-and-pii).
* **Scoped access** — Tokens are restricted to specific scopes and optionally to specific events.
* **Audit logging** — Every API call is recorded with source, method, response time, and token ID. For `ask_event` the question text is redacted from the log.

## Example Conversations

Once connected, you can ask questions like:

* "How many sessions are accepted for this year's conference?"
* "Show me the top 10 speakers by number of sessions."
* "What's the breakdown of sessions by track and status?"
* "List all sessions that don't have a room assigned yet."
* "Which sessions cover cardiac imaging, and what did the speakers say about it?"
* "Create a new track called 'AI & Machine Learning' with color #4F46E5."
* "Build a dashboard showing session counts by status and track."
* "Create a draft agenda and schedule the keynote in the Main Hall at 9am."


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.