ScoreStory

npx add-mcp 'https://app.scorestory.eu/api/mcp'

Getting started

1. Create a token inside the app, as an admin, under Organisation → API tokens. Scope it to only what your integration needs, and set an expiry if you can.
2. Call GET /api/public-api/v1/me to check which workspace, scopes and survey restriction the token has.
3. Make your first call:

# 1. What can this token do?
curl -s https://app.scorestory.eu/api/public-api/v1/me \
  -H "Authorization: Bearer $SCORESTORY_TOKEN"

# 2. Create a survey (required: name, metric_type, interview_locale)
#    metric_type: nps | enps | csat | ces | scale
curl -s -X POST https://app.scorestory.eu/api/surveys \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 pulse","metric_type":"nps","interview_locale":"en"}'

# 3. Invite someone
curl -s -X POST https://app.scorestory.eu/api/surveys/<survey_id>/invitations/personal \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_email":"sam@example.com","recipient_name":"Sam"}'

What you can do

• Create, read, update, clone and delete surveys
• Manage respondent properties and themes
• Create, reissue, revoke and email personal invitations and shared links
• Read respondents and their transcripts; erase a respondent (GDPR)
• Read results: overview, individual scores, written conclusion, themes with quotes, trend over time
• Create, schedule, send, pause and read statistics for mailings

Ground rules

Rate limits are per token; a 429 response carries a Retry-After header telling you how long to wait. Errors always look like {"error": {"code": "...", "message": "..."}} — branch on code, not on the message text. Versioning is additive: fields are only added within a major version, never removed or repurposed. There are no webhooks yet — poll the results endpoints.

Connect an AI assistant (MCP)

ScoreStory has an MCP server, so an AI assistant such as Claude or ChatGPT can work in your workspace: create a survey from a short brief, invite people and read the results. You sign in with your own ScoreStory account. There is no token to copy.

https://app.scorestory.eu/api/mcp

• Transport: Streamable HTTP
• Authentication: OAuth 2.1 with dynamic client registration. Your assistant registers itself and sends you to ScoreStory to approve the connection.

Setting it up

1. Add ScoreStory to your assistant with the server URL above:
   • Claude: Settings → Connectors → Add custom connector, and paste the URL.
     • ChatGPT: add a custom connector in ChatGPT's settings and paste the same URL.
     • Other MCP clients: add a remote MCP server with this URL. In Claude Code, for example: claude mcp add --transport http scorestory https://app.scorestory.eu/api/mcp
2. The assistant sends you to ScoreStory. Sign in as usual.
3. Pick the workspace the assistant may work in.
4. Tick what it may do. The read permissions are on by default; you tick the write permissions on purpose.
5. Read the yellow warning, then click Allow. You go back to the assistant, which can now use the tools below.

Only workspace administrators can connect an app. The connection acts on your behalf, with the same rights you have in that workspace.

What the assistant can do

Ten tools. The read tools only read; the write tools create things. No tool deletes data, sends e-mail or changes billing.

Read

• List surveys (list_surveys): the surveys in the workspace, with status and response counts
• Get survey details (get_survey): one survey's metric, language, themes and participant properties
• List respondents (list_respondents): who was invited, who started and who finished
• Read interview transcript (read_transcript): one participant's interview, turn by turn, with its summary and topics
• Get survey results (get_results): the score, the themes with their sentiment, and the written conclusion
• Get quotes for a topic (get_topic_quotes): what participants said about one theme

Write

• Create survey (create_survey): a new NPS, eNPS, CSAT, CES or custom-scale survey. Nothing is sent.
• Add theme (add_theme): a theme for the AI interviewer to explore
• Create shared survey link (create_shared_link): one link anyone can open, for a newsletter, a QR code or the intranet
• Create personal invitation (invite_participant): a private link for one person, which you send yourself

Managing access

Under Organisation → API tokens → Connected apps you see which apps are connected, who connected them and when each was last used. The server URL is shown there too. Disconnect ends a connection. Everything an assistant does is written to the workspace's audit log, together with the app's name.

Troubleshooting

• "No workspace to connect." You are not an administrator of any workspace, and only administrators can connect an app. Ask an administrator to connect it, or to give you that role.
• You clicked Deny, or picked the wrong workspace. Start the connection again from your assistant and choose again. Disconnect the wrong workspace under Connected apps.
• The assistant says a permission is missing. It was not ticked when you connected. Connect again and tick it.
• The assistant lost access after you left the workspace. The connection has your rights, so when you lose access to the workspace, the assistant does too. Someone who is still an administrator there has to connect it.
• The assistant says its token has expired. The assistant renews its access by itself; the refresh token lasts 30 days from its last use. After 30 days without use, or after a disconnect, connect again.
• The yellow warning on the consent screen. It names the address the access goes to. Anyone can register an app under any name, so the name and logo prove nothing; the address does. Click Allow only if you started the connection yourself from that app. If someone else sent you the link, deny.

Which AI processes the data

What the tools return goes to the assistant you connected, under that assistant's own terms. Inside ScoreStory, interviews are conducted and analysed by the AI model your organisation chooses under Organisation → AI model: Mistral, in the EU, or Claude, from Anthropic in the United States. The privacy statement explains what each choice means for your participants' data.

For AI agents

If you're an agent acting on someone's behalf, start at llms.txt. It has the same information laid out for machine reading. If your client speaks MCP, connect to the MCP server: the person you work for signs in and approves the connection, and no token changes hands. Otherwise you'll need a workspace API token: there is no way to create one programmatically, so ask the person you're working for to make one under Organisation → API tokens and hand it to you.

Questions

Reach us at welcome@scorestory.eu.

---

Last updated: 27 October 2026.