MCP Integration — SeggWat Docs

Overview

SeggWat includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Claude Desktop to interact directly with your feedback and rating data. This integration allows AI tools to:

Query feedback: List, search, and retrieve feedback items
Manage feedback: Create, update, and archive feedback
Access ratings: View and analyze helpfulness ratings
Manage surveys: List surveys, read response stats, create from templates, and change status
Automate workflows: Process feedback with AI-powered analysis
Generate insights: Analyze feedback trends and patterns

The MCP server is hosted at the /mcp endpoint. Claude can connect over OAuth as a custom connector — no manual token, you only enter the server URL — or any MCP client can authenticate with an API key.

Prerequisites

Before you start, ensure you have:

A SeggWat account with at least one project, and admin or owner access to your organization
An MCP-compatible client. Claude (web, desktop, and Claude Code) connects over OAuth with no setup; other clients (Cline, custom clients) use an API key

Connecting Claude (Recommended)

The easiest way to connect is to add SeggWat as a custom connector in Claude. Claude handles authentication over OAuth, so you never create or paste an API key — you only enter the server URL. This works in Claude on the web, the desktop app, and Claude Code.

Open connector settings

In Claude, go to Settings → Connectors and click Add custom connector.

Enter the server URL

Enter your SeggWat MCP URL and confirm:

https://seggwat.com/mcp

Claude registers itself automatically (Dynamic Client Registration) — there's no client ID or secret to configure.

Authorize

Claude opens SeggWat to authorize the connection:

- If you're already signed in to the [SeggWat Dashboard](https://seggwat.com/dashboard), approve with a single click on the consent screen.
- Otherwise, sign in with your email and the one-time code sent to your inbox, then approve.

The connection authorizes against your organization, so you need **admin or owner** access (the same requirement as creating an API token).

Start using it

Claude can now call the SeggWat tools. Try: "List my SeggWat projects."

Note

Authorizing creates a long-lived access token labelled Claude (MCP) in your dashboard under Settings → API Tokens. To disconnect, revoke that token there (or remove the connector in Claude).

Tip

Self-hosting? Use your own domain as the connector URL — https://your-seggwat-domain.com/mcp. The OAuth endpoints are served from the same deployment.

Connecting with an API Key

If your client doesn't support custom connectors (e.g. Cline, custom MCP clients) — or you prefer a static token — authenticate with an Organization Access Token instead. Keep the token secure and never commit it to version control.

1. Get Your API Token

Navigate to Settings

Generate Token

Go to the API Tokens tab and click Create New Token. Add a descriptive label like "Claude Desktop MCP".

Copy Token

Copy the token immediately - it will only be shown once! You'll use this in the next step.

2. Configure Claude Desktop

Add SeggWat to your Claude Desktop configuration file:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
      "mcpServers": {
        "seggwat": {
          "type": "http",
          "url": "https://seggwat.com/mcp",
          "headers": {
            "Authorization": "Bearer oat_your_api_token_here"
          }
        }
      }
    }

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop to load the new MCP server.

4. Verify Connection

In Claude Desktop, try asking:

"List my SeggWat projects"

Claude should now be able to access your SeggWat data through the MCP server.

Available Tools

The MCP server provides the following tools:

Projects

list_projects

List all projects in your organization.

Returns: Array of projects with IDs, names, and keys.

Feedback Management

list_feedback

List feedback with filtering and pagination.

**Parameters:**
- `project_id` (required)
- `page`, `limit` (optional)
- `status`, `type`, `search` (optional filters)

get_feedback

Get a single feedback item by ID.

**Parameters:**
- `project_id` (required)
- `feedback_id` (required)

create_feedback

Create new feedback programmatically.

**Parameters:**
- `project_id` (required)
- `message` (required)
- `type`, `source`, `path`, `version` (optional)

update_feedback

Update feedback status, type, or message.

**Parameters:**
- `project_id`, `feedback_id` (required)
- `status`, `type`, `message` (optional)

delete_feedback

Archive a feedback item.

**Parameters:**
- `project_id`, `feedback_id` (required)

Ratings Management

list_ratings

List helpfulness ratings with filtering.

**Parameters:**
- `project_id` (required)
- `page`, `limit` (optional)
- `value`, `search` (optional filters)

get_rating

Get a single rating by ID.

**Parameters:**
- `project_id`, `rating_id` (required)

create_rating

Create a new rating programmatically.

**Parameters:**
- `project_id` (required)
- `value` (required, boolean)
- `path`, `version` (optional)

delete_rating

Archive a rating.

**Parameters:**
- `project_id`, `rating_id` (required)

get_rating_stats

Get aggregated rating statistics.

**Parameters:**
- `project_id` (required)
- `path` (optional, filter by page)

Survey Management

Surveys are created from canonical templates in draft status, then flipped to live. Fine-grained question and trigger editing happens in the dashboard — the MCP tools cover listing, reading stats, template creation, and status changes.

Note

Creating and editing drafts works on any plan. Setting a survey to live (publishing) requires the Pro plan — set_survey_status with status: live returns 403 Forbidden for non-Pro orgs.

list_surveys

List all surveys for a project, with response counts.

**Parameters:**
- `project_id` (required)

get_survey

Get a single survey's full definition.

**Parameters:**
- `project_id`, `survey_id` (required)

get_survey_stats

Get aggregated per-question response statistics.

**Parameters:**
- `project_id`, `survey_id` (required)

create_survey

Create a survey from a template (lands in draft).

**Parameters:**
- `project_id` (required)
- `template` (required): `blank`, `nps`, `csat`, or `ces`

set_survey_status

Change a survey's lifecycle status.

**Parameters:**
- `project_id`, `survey_id` (required)
- `status` (required): `draft`, `live`, `paused`, or `archived`

Usage Examples

Here are some common tasks you can perform with Claude Desktop connected to SeggWat:

Analyze Recent Feedback

"Show me the latest 10 feedback items from my main project and summarize the key themes"

Claude will:

List your projects
Fetch recent feedback
Analyze and summarize the content

Find Bug Reports

"Find all bug-type feedback from the last week that hasn't been addressed yet"

Claude will:

Filter feedback by type="Bug" and status="New"
Present the results
Optionally help you prioritize them

Monitor Page Helpfulness

"What's the helpfulness score for the /docs/getting-started page?"

Claude will:

Fetch rating statistics for that path
Calculate the helpfulness percentage
Show trends if available

Bulk Update Status

"Mark all feedback from yesterday as 'In Progress'"

Claude will:

List feedback from the specified timeframe
Update each item's status
Confirm the changes

Export for Analysis

"Create a markdown report of all high-priority feedback from this month"

Claude will:

Fetch filtered feedback data
Format it as a structured markdown report
Include relevant metadata and statistics

Spin Up an NPS Survey

"Create an NPS survey on my main project and tell me when it's ready to go live"

Claude will:

Create a survey from the nps template (it starts in draft)
Return the new survey's ID
Set its status to live once you confirm

Review Survey Results

"How is my CSAT survey performing? Summarize the responses."

Claude will:

Find the survey with list_surveys
Fetch get_survey_stats for it
Summarize per-question scores and response counts

Authentication Options

When connecting Claude as a custom connector, authentication is handled for you over OAuth — you can skip this section. For the API-key path, the MCP server accepts the token in either header:

Bearer Token (Recommended)

json

{
  "headers": {
    "Authorization": "Bearer oat_your_api_token_here"
  }
}

API Key Header

json

{
  "headers": {
    "X-API-Key": "oat_your_api_token_here"
  }
}

Both methods are equivalent - use whichever fits your client's configuration style.

Security Best Practices

Troubleshooting

Connection Issues

Problem: Claude Desktop can't connect to SeggWat MCP server

Verify URL

Ensure the URL is exactly https://seggwat.com/mcp (no trailing slash)

Check API Token

Verify your API token is valid in the SeggWat dashboard under Settings → API Tokens

Test Manually

Test the connection with curl:

bash

curl -X POST https://seggwat.com/mcp \
      -H "Authorization: Bearer oat_your_token" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Review Logs

Check Claude Desktop logs for error messages: - macOS: ~/Library/Logs/Claude/mcp*.log - Windows: %APPDATA%\Claude\logs\mcp*.log

Permission Errors

Problem: "Access denied" or 403 errors

The API token might not have access to the requested projects. Ensure:

The token belongs to the same organization as the projects
The token hasn't been revoked
Your account has appropriate permissions

Rate Limiting

Problem: "Too many requests" errors

The MCP endpoint uses the same rate limits as the REST API:

20 requests per minute for feedback endpoints
If you hit limits, Claude will need to slow down its requests

Advanced Configuration

Custom Headers

Add custom headers for tracking or debugging:

json

{
  "headers": {
    "Authorization": "Bearer oat_your_token",
    "X-Client-Name": "Claude-Desktop",
    "X-Client-Version": "1.0.0"
  }
}

Using with Other MCP Clients

While this guide focuses on Claude Desktop, the SeggWat MCP server works with any MCP-compatible client:

Custom MCP Clients

For building custom MCP clients, see the Model Context Protocol specification.

The SeggWat MCP server implements:

HTTP transport with streaming support
Standard MCP protocol (tools, resources, prompts)
Bearer token and X-API-Key authentication

Performance Considerations

Tip

The MCP server uses the same backend as the REST API, so performance characteristics are identical:

Average response time: < 100ms for list operations
Supports pagination for large datasets
Results are cached for 60 seconds

For optimal performance:

Use pagination (page and limit parameters)
Apply filters to narrow results
Cache project IDs locally in your workflows

Next Steps

API Reference

Complete API documentation (MCP tools mirror these endpoints)

API Integration

Learn about direct REST API integration

List Feedback

Detailed documentation for the list feedback endpoint

Rating Statistics

Learn about rating aggregation and analytics