MCP Server

MCP Server

Model Context Protocol (MCP) is a standard that lets AI models (Claude, Cursor, Copilot, etc.) connect to SurveyNinja and work with your data directly — read surveys, responses, analytics, and perform actions without manual copying.

1. Connection

Endpoint

Two ways to connect

• Allow access (recommended). Add the server address to your assistant, sign in to SurveyNinja when it asks, choose a workspace and click Allow access. No key is needed: the assistant works in the workspace you chose and renews access by itself.
• API key. For clients that cannot sign in, or when one assistant should work in every workspace where you are the owner or a member. Pass the key in a header, as shown below.

Claude

1. In Claude on the web or in the desktop app, open Settings, then Connectors, and click Add custom connector.
2. Enter a name, for example SurveyNinja, and the server address.
3. Click Add, then Connect, and allow access in SurveyNinja.

On Claude Team and Enterprise, an organization owner adds the connector first, then each member connects it.

ChatGPT

1. Turn on developer mode in the ChatGPT settings. It is available on some ChatGPT plans.
2. Create a connector with the server address and OAuth authentication.
3. Allow access in SurveyNinja.

Claude Code

Run the command in the terminal, then type /mcp in Claude Code, select surveyninja and sign in.

claude mcp add --transport http surveyninja https://mcp.surveyninja.io/mcp/v1

With the ready-made skills, as a plugin that adds the server and every skill in one install:

/plugin marketplace add surveyninjaio/surveyninja-mcp /plugin install surveyninja@surveyninja

Cursor

Add the server to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json for one project. Then open the MCP section in the Cursor settings and sign in to the surveyninja server.

{
  "mcpServers": {
    "surveyninja": {
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your project, start it from the file and sign in when VS Code asks. The server works in GitHub Copilot Chat in agent mode.

{
  "servers": {
    "surveyninja": {
      "type": "http",
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

Getting an API key

1. Log in to your SurveyNinja account.
2. Go to Settings → API / MCP.
3. Click "Create API key" and copy it — the key is shown only once.

Authentication

Pass the API key in the Authorization header:

For a client that takes the mcpServers format with headers, replace YOUR_API_KEY with your key:

{
  "mcpServers": {
    "surveyninja": {
      "url": "https://mcp.surveyninja.io/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configs for every client and the skills as files: github.com/surveyninjaio/surveyninja-mcp.

Rate limits

• 180 requests per minute per user (tools/call, resources/read, etc.)
• Export links are valid for 1 hour

2. Resources

Resources are read-only. To use them, send a resources/read request with the corresponding URI.

3. Tools

Tools are actions executed on the SurveyNinja side upon request from an AI model via the tools/call method.

Survey management

Survey content and structure

Design themes

Survey variables

Hidden options

Responses, analytics and public links

Export

All tools accept quiz_id (required). Download link is valid for 1 hour.

Promo codes (paid plan)

4. Technical details

Standard JSON-RPC methods

Request example

POST https://mcp.surveyninja.io/mcp/v1 Authorization: Bearer 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "rename_quiz", "arguments": { "quiz_id": 123, "name": "New survey name" } } }

Error response format

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: quiz_id is required" } }

5. Typical scenarios