Model Context Protocol (MCP) server

What it is

Aclamos runs a Model Context Protocol (MCP) server at https://aclamos.app/api/mcp/v1. An MCP-capable AI client connected to it can look up your org's shows, categories, nominations, judges, judging progress, Ballotis polls and winners, so you can ask questions like "How many nominations are in Best Documentary?" against live data.

Available on the Studio and Enterprise plans. Both get 10 read-only tools. Enterprise also gets 3 write tools. Other plans get a 402 plan-required response.

Setup

1. As an org Admin or Owner, open /[your-org]/api-keys.
2. Create a new key and tick the mcp:read scope. A key without mcp:read is refused with 403 missing-scope.
3. Copy the key now. It is shown on the page right after you create it and never appears in the key list afterwards.
4. In your MCP client, add a server with:

- URL: https://aclamos.app/api/mcp/v1 (Streamable HTTP) - Header: Authorization: Bearer <your key>

Your dashboard's Integrations → MCP server page (/[your-org]/integrations/mcp) shows the endpoint, whether you already have an mcp:read key, a sample config block and the full tool list, with Enterprise-only tools marked.

The server authenticates with that bearer key only. It has no OAuth sign-in, so a client that can only connect through an OAuth sign-in flow cannot connect to it directly. Client setup screens vary; check your client's MCP docs for how to add a remote server with a custom header.

Read-only tools (Studio and Enterprise)

• list_shows: list the shows in your org.
• list_categories: list the categories for a show (by show slug).
• list_nominations: list nominations for a show, with an optional status filter.
• get_nomination: fetch one nomination's full record by its public ID, including free-text responses.
• list_judges: list the judges in your org.
• get_judging_progress: for a judging round (by round ID; note that no MCP tool returns round IDs and the dashboard does not show them yet), one row per assignment showing the judge and that judge's submitted-review count.
• list_polls: list Ballotis polls in your org, with an optional status filter.
• get_poll_tally: vote counts per option for a poll. Follows the poll's results settings: with live results on, the tally is available at any time; otherwise only once the poll is closed and "show results after close" is on. If neither applies, it returns an error instead of a tally.
• list_winners: list winners for a show.
• search_nominations: text search across nominations by nominee name, nominator name, nominee or nominator email, or public ID.

Every tool is scoped to the org that owns the key. No tool takes an org parameter.

Write tools (Enterprise only)

Each write tool requires confirm: true in the call. Without it the call is rejected.

• post_judge_comment: set the comment on an existing review. This replaces any comment already there.
• set_nomination_status: change a nomination's status to any of the 12 nomination statuses (for example SUBMITTED, IN_REVIEW, FINALIST or WINNER). Any status can move to any other; nothing else happens (no emails). Setting WINNER does not declare a winner: declare winners in the dashboard so they show in list_winners.
• advance_cue: mark a show's current run-of-show cue completed and make the next cue current. Takes the show's ID from list_shows, not its slug. Start the show in the run-of-show screen first; on the last cue it completes it and leaves no cue current.

Each write is recorded in your org's audit log as mcp.<tool>.invoked. Read-only tool calls are not written to the audit log.

Rate limits

120 requests per minute per org, on every plan that has MCP. Every request to the endpoint counts, including your client's connection handshake. Requests above that get a 429 rate-limited response; wait and retry. A missing, invalid or revoked key gets 401 unauthorized.

Security

• API keys are stored as SHA-256 hashes.
• Tool results go to your AI client. get_nomination includes nominee and nominator emails, and list_judges includes judge emails.
• Keys created from the dashboard do not expire on their own. Revoke a key at any time from /[your-org]/api-keys; it stops working immediately.

Cost

MCP access is included in the Studio and Enterprise plans. The AI model runs in your own client, so its usage is billed by your AI provider, not by Aclamos.