> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuteliq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Install and use the Tuteliq MCP server for AI assistant integrations

The Tuteliq MCP server (`@tuteliq/mcp` v3.7.0) exposes child safety detection as tools for AI assistants that support the [Model Context Protocol](https://modelcontextprotocol.io) — including Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients.

## Setup

### Claude Desktop (Recommended)

Claude Desktop connects to Tuteliq via Streamable HTTP — no npm install required.

<Steps>
  <Step title="Generate a Secure Token">
    Go to your [Tuteliq Dashboard](https://tuteliq.ai/dashboard), navigate to **Settings > Plugins**, and generate a **Secure Token**. This token authenticates the MCP connection.
  </Step>

  <Step title="Add the connector in Claude Desktop">
    1. Open Claude Desktop and go to **Settings > Connectors**
    2. Click **Add custom connector**
    3. Set the name to **Tuteliq** and the URL to:
       ```
       https://api.tuteliq.ai/mcp
       ```
  </Step>

  <Step title="Connect and authenticate">
    Click **Connect**. When prompted, enter the Secure Token you generated in Step 1.

    That's it — Tuteliq tools will be available in your next conversation.
  </Step>
</Steps>

### Cursor

Add to your Cursor MCP settings:

```json theme={"dark"}
{
  "mcpServers": {
    "tuteliq": {
      "url": "https://api.tuteliq.ai/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json`:

```json theme={"dark"}
{
  "mcpServers": {
    "tuteliq": {
      "url": "https://api.tuteliq.ai/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

### Other MCP clients (npx / stdio)

For clients that only support stdio transport:

```bash theme={"dark"}
npm install -g @tuteliq/mcp
```

```json theme={"dark"}
{
  "mcpServers": {
    "tuteliq": {
      "command": "tuteliq-mcp",
      "env": {
        "TUTELIQ_API_KEY": "your_api_key"
      }
    }
  }
}
```

## Available tools

Once configured, the following tools are available to the AI assistant:

### Detection tools

All detection tools accept a common set of parameters:

| Parameter           | Type      | Required | Description                                                                                                                                                                              |
| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`           | `string`  | Yes      | Text content to analyze                                                                                                                                                                  |
| `context`           | `object`  | No       | Analysis context — see [Context fields](#context-fields) below                                                                                                                           |
| `include_evidence`  | `boolean` | No       | When `true`, returns supporting evidence excerpts with flagged phrases and weights                                                                                                       |
| `support_threshold` | `string`  | No       | Minimum severity to include crisis helplines. Values: `low`, `medium`, `high` (default), `critical`. Critical severity **always** includes support resources regardless of this setting. |
| `external_id`       | `string`  | No       | Your external tracking ID (echoed in response)                                                                                                                                           |
| `customer_id`       | `string`  | No       | Your customer identifier (echoed in response)                                                                                                                                            |

| Tool                                | Description                                                                         |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `detect_unsafe`                     | Detect harmful content across all nine KOSA categories                              |
| `detect_bullying`                   | Detect bullying and harassment patterns                                             |
| `detect_grooming`                   | Detect grooming patterns in conversations                                           |
| `detect_social_engineering`         | Detect social engineering tactics (pretexting, impersonation, urgency manipulation) |
| `detect_app_fraud`                  | Detect app-based fraud (fake investments, phishing, subscription traps)             |
| `detect_romance_scam`               | Detect romance scam patterns (love-bombing, financial requests, identity deception) |
| `detect_mule_recruitment`           | Detect money mule recruitment (easy-money offers, account sharing)                  |
| `detect_gambling_harm`              | Detect gambling harm indicators (chasing losses, concealment, underage gambling)    |
| `detect_coercive_control`           | Detect coercive control patterns (isolation, financial control, surveillance)       |
| `detect_vulnerability_exploitation` | Detect exploitation targeting vulnerable individuals                                |
| `detect_radicalisation`             | Detect radicalisation indicators (extremist rhetoric, recruitment patterns)         |

### Multi-endpoint analysis

`analyse_multi` runs up to 10 detections on a single text in one call.

| Parameter           | Type       | Required | Description                                                        |
| ------------------- | ---------- | -------- | ------------------------------------------------------------------ |
| `content`           | `string`   | Yes      | Text content to analyze                                            |
| `endpoints`         | `string[]` | Yes      | List of endpoint IDs to run (see table below)                      |
| `context`           | `object`   | No       | Analysis context — see [Context fields](#context-fields)           |
| `include_evidence`  | `boolean`  | No       | Include supporting evidence in each result                         |
| `support_threshold` | `string`   | No       | Crisis helpline threshold (`low` / `medium` / `high` / `critical`) |

**Valid endpoint values for `analyse_multi`:**

| Endpoint ID                  | Classifier                       |
| ---------------------------- | -------------------------------- |
| `bullying`                   | Bullying & Harassment            |
| `grooming`                   | Grooming Detection               |
| `unsafe`                     | Unsafe Content (KOSA categories) |
| `social-engineering`         | Social Engineering               |
| `app-fraud`                  | App-based Fraud                  |
| `romance-scam`               | Romance Scam                     |
| `mule-recruitment`           | Mule Recruitment                 |
| `gambling-harm`              | Gambling Harm                    |
| `coercive-control`           | Coercive Control                 |
| `vulnerability-exploitation` | Vulnerability Exploitation       |
| `radicalisation`             | Radicalisation                   |

<Info>
  When `vulnerability-exploitation` is included, its cross-endpoint modifier automatically adjusts severity scores across all other results — amplifying risk when the content targets vulnerable individuals.
</Info>

### Media analysis tools

| Tool            | Parameters               | Description                                        |
| --------------- | ------------------------ | -------------------------------------------------- |
| `analyze_voice` | `file_path`, `age_group` | Transcribe and analyze audio files for safety      |
| `analyze_image` | `file_path`, `age_group` | Analyze image files for visual content risks       |
| `analyze_video` | `file_path`, `age_group` | Analyze video files with per-frame safety findings |

### Guidance & reporting tools

| Tool               | Parameters                             | Description                                                                  |
| ------------------ | -------------------------------------- | ---------------------------------------------------------------------------- |
| `analyze_emotions` | `content`, `context`                   | Analyze emotional well-being from text                                       |
| `get_action_plan`  | `detection_result`, `audience`         | Generate age-appropriate guidance (`child`, `parent`, `professional`)        |
| `generate_report`  | `messages`, `childAge`, `incidentType` | Create structured incident reports for law enforcement or safeguarding teams |

## Context fields

Pass a `context` object with any detection tool to improve accuracy:

| Field                    | Type     | Effect                                                                                                                                             |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ageGroup` / `age_group` | `string` | Triggers age-calibrated scoring. Values: `"under 10"`, `"10-12"`, `"13-15"`, `"16-17"`, `"under 18"`                                               |
| `language`               | `string` | ISO 639-1 code (e.g., `"en"`, `"de"`, `"sv"`). Auto-detected if omitted.                                                                           |
| `platform`               | `string` | Platform name (e.g., `"Discord"`, `"Roblox"`, `"WhatsApp"`). Adjusts for platform-specific norms.                                                  |
| `conversation_history`   | `array`  | Prior messages for context-aware analysis. Returns per-message `message_analysis`.                                                                 |
| `sender_trust`           | `string` | `"verified"`, `"trusted"`, or `"unknown"`.                                                                                                         |
| `sender_name`            | `string` | Sender identifier (used with `sender_trust`).                                                                                                      |
| `country`                | `string` | ISO 3166-1 alpha-2 code (e.g., `"GB"`, `"US"`, `"SE"`). Enables geo-localised crisis helpline data. Falls back to user profile country if omitted. |

<Info>
  When `sender_trust` is `"verified"`, the API fully suppresses `AUTH_IMPERSONATION` — a verified sender cannot be impersonating an authority by definition. Routine urgency (schedules, deadlines) is also suppressed. Only genuinely malicious content (credential theft, phishing links, financial demands) will be flagged.
</Info>

## Example usage

Once the MCP server is running, you can ask your AI assistant to use Tuteliq tools directly in conversation:

> "Check this message for safety: 'Let's meet at the park after school, don't tell your parents' — the user is 10-12 years old"

The assistant will call `detect_unsafe` and return the full safety analysis including severity, categories, risk score, and rationale.

> "Analyze this conversation for grooming patterns" (with a conversation pasted or in a file)

The assistant will call `detect_grooming` and provide a detailed breakdown of any detected grooming stages.

> "Check this message for social engineering: 'If you really trusted me you'd send your address'"

The assistant will call `detect_social_engineering` and return whether manipulation tactics were detected.

> "Run grooming, romance scam, and social engineering detection on this message"

The assistant will call `analyse_multi` with all three endpoints and return combined results with an overall risk level.

> "Analyze this video for safety concerns" (with a file path)

The assistant will call `analyze_video` and return frame-by-frame safety findings.

## Resources

The MCP server also exposes resources for context:

| Resource                    | Description                                        |
| --------------------------- | -------------------------------------------------- |
| `tuteliq://kosa-categories` | List of all nine KOSA harm categories              |
| `tuteliq://age-groups`      | Available age group brackets and their calibration |
| `tuteliq://credit-costs`    | Per-endpoint credit costs                          |

## Stateless by Design

Tuteliq is **fully stateless** — no conversation text, context, or session state is retained between requests. This is a deliberate **privacy-by-design** decision.

When processing messages from minors under GDPR/COPPA, the safest data is data you never store. Each request arrives, is analyzed, and the content is discarded. Pass `context` (age\_group, platform, conversation\_history) with every call that needs it.

```
You: "Check this message for grooming. The user is 13-15 on Discord: 'Hey, you seem really mature for your age'"
→ Tuteliq analyzes with age-calibrated scoring — no data retained

You: "Now check this follow-up with the previous message as context: 'Don't tell your parents about our chats'"
→ Pass conversation_history in context — Tuteliq detects escalation patterns across the full conversation
```

<Info>
  **Privacy-first:** No session store to breach, no conversation cache to leak, no accumulated history to subpoena. Your integration handles context; Tuteliq handles detection.
</Info>

## Sandbox mode

For testing without consuming credits, use a sandbox API key. Create one in your [Dashboard](https://tuteliq.ai/dashboard) under **Settings > API Keys > Environment: Sandbox**.

Sandbox keys:

* Run **real analysis** (not mocked) so you can validate integration behavior
* **Don't consume credits** — `credits_used` is always 0
* Have a **daily limit of 50 calls** and **10 requests per minute**
* Return `"sandbox": true` in every response

<Warning>
  Sandbox mode is for integration testing only. For production use, switch to a production API key.
</Warning>

## Error handling

If the API key is invalid or credits are exhausted, the tool will return a structured error message that the AI assistant can interpret and relay to the user.

## Configuration options

Environment variables:

| Variable           | Description           | Default                  |
| ------------------ | --------------------- | ------------------------ |
| `TUTELIQ_API_KEY`  | Your Tuteliq API key  | Required                 |
| `TUTELIQ_BASE_URL` | API base URL          | `https://api.tuteliq.ai` |
| `TUTELIQ_TIMEOUT`  | Request timeout in ms | `30000`                  |

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API specification.
  </Card>

  <Card title="CLI" icon="terminal" href="/sdks/cli">
    See the CLI guide.
  </Card>
</CardGroup>