# SatisMeter MCP

Read-only remote MCP server for exposing SatisMeter survey data to Claude custom connectors.

It is designed for NPS response analysis, but also exposes project, survey, response, and statistics reads from the SatisMeter API. The server runs as a Vercel serverless function and implements OAuth dynamic client registration so Claude can connect to it as a remote MCP connector.

## What It Does

- Lets Claude read SatisMeter project metadata.
- Lists and finds surveys, including likely NPS surveys.
- Reads paginated survey or project responses.
- Reads survey statistics.
- Supports a default project ID so Claude users do not need to include `projectId` in prompts.
- Keeps the SatisMeter API key server-side in Vercel environment variables.

## Deploy Your Own

This repository is optimized for Vercel. The MCP server is implemented as a Vercel serverless function in `api/mcp.ts`, with routing defined in `vercel.json`.

1. Fork or clone this repository.
2. Create a Vercel project from the fork.
3. Add the environment variables below in Vercel.
4. Deploy to production.
5. Add the deployed URL as a Claude custom connector.

## Environment Variables

Set these in Vercel:

| Name | Required | Description |
| --- | --- | --- |
| `SATISMETER_API_KEY` | Yes | SatisMeter API key. Stored only server-side. |
| `OAUTH_SIGNING_SECRET` | Yes | Random secret used to sign OAuth authorization codes and access tokens. Generate with `openssl rand -hex 48`. |
| `SATISMETER_PROJECT_ID` | Recommended | Default SatisMeter project ID. Recommended so Claude can fetch NPS responses without asking for `projectId`. |
| `SATISMETER_NPS_SURVEY_ID` | Optional | Default NPS survey ID. If omitted, the MCP finds a likely NPS survey from the configured project. |

Project and survey IDs are available in SatisMeter under **Settings > Integrations > API**.

## Claude Connector URL

Use either URL in Claude:

```text
https://<your-vercel-domain>
https://<your-vercel-domain>/mcp
```

The bare deployment host routes to the MCP endpoint for Claude compatibility.

## Tools

- `satismeter_list_surveys`: Lists surveys for a project.
- `satismeter_get_project`: Reads project metadata by ID.
- `satismeter_find_nps_surveys`: Finds likely NPS surveys by type or name.
- `satismeter_get_survey`: Reads survey metadata.
- `satismeter_get_survey_responses`: Reads paginated responses from one survey.
- `satismeter_get_nps_responses`: Reads paginated responses from the configured or discovered NPS survey.
- `satismeter_get_project_responses`: Reads paginated responses across a project.
- `satismeter_get_survey_statistics`: Reads survey statistics.

SatisMeter does not expose a `GET /projects` endpoint, so this MCP cannot list all projects. Configure `SATISMETER_PROJECT_ID` or pass `projectId` explicitly.

## Claude Team Setup

An Owner or Primary Owner can add the hosted URL in Claude:

1. Open Organization settings > Connectors.
2. Add > Custom > Web.
3. Paste the Vercel deployment URL.
4. Add the connector and complete the OAuth prompt.

Team members then enable it under Customize > Connectors.

## Security Notes

- Do not put `SATISMETER_API_KEY` in Claude connector settings or in the URL.
- The SatisMeter API key is read from `process.env.SATISMETER_API_KEY` at runtime.
- OAuth tokens issued by this server only grant access to this MCP server; they are not SatisMeter API keys.
- The MCP is read-only.

## API Reference

SatisMeter API docs: <https://app.satismeter.com/apidoc>