# Setup the Netmera MCP Server

Use this guide to connect Netmera MCP Server to your client and start using it safely.

### Before you start

Make sure you have:

1. access to the target Netmera app,
2. an MCP-compatible environment that supports connectors or MCP access,
3. and the correct permission level in the Netmera panel.

### Access model

Each token is tied to one Netmera app. The token also inherits your panel permissions. Your client cannot exceed them.

#### Scopes

<table><thead><tr><th width="135.90008544921875">Scope</th><th width="345.85986328125">What it allows</th><th>Best for</th></tr></thead><tbody><tr><td><code>mcp:read</code></td><td>Reporting, inspection, analytics, and lookups</td><td>Safe analysis and exploration</td></tr><tr><td><code>mcp:write</code></td><td><code>mcp:read</code> plus create, update, send, pause, resume, and approval actions</td><td>Operational tasks with human control</td></tr></tbody></table>

Tools marked with `🔒` require `mcp:write`.

#### Token lifetime

<table><thead><tr><th width="322.541259765625">Token type</th><th>Lifetime</th></tr></thead><tbody><tr><td>JWT</td><td>30 days</td></tr><tr><td>OAuth access token</td><td>8 hours</td></tr></tbody></table>

{% hint style="warning" %}
Start with `mcp:read`. Move to `mcp:write` only when you need write access.
{% endhint %}

### Connect Netmera MCP Server

{% stepper %}
{% step %}

#### Request a token

If your environment supports direct connector sign-in, complete the login flow when prompted.

You can also request a token directly:

```json
POST https://<panel-address>/ai/mcp/auth/token
Content-Type: application/json

{
  "email": "your@email.com",
  "password": "your-netmera-password",
  "scope": "mcp:read"
}
```

{% endstep %}

{% step %}

#### Add Netmera in your client

Add Netmera as a connector or MCP source in your client.

Then sign in and approve access for the target app.
{% endstep %}

{% step %}

#### Test the connection

* “What is the health status of my app today?”
* “How many users are in the VIP segment?”
* “Show daily revenue for the last 30 days.”
  {% endstep %}

{% step %}

### Upgrade the scope when needed

Regenerate the token with `scope: "mcp:write"` when you want to create drafts or perform approved actions.
{% endstep %}
{% endstepper %}

### First setup checks

After you connect, confirm these basics before moving on:

* You are connected to the expected app.
* Dashboards and reports return data.
* Write functions stay unavailable unless you enabled `mcp:write`.

#### What to include in a prompt

Include these details when relevant:

1. **Time range** — such as “last 7 days”, “yesterday”, or “this month”
2. **Target** — such as a channel, campaign, segment, user, workflow, or event
3. **Output** — such as a summary, ranking, comparison, trend, or draft
4. **Action boundary** — such as “prepare only”, “show preview”, or “do not send”

#### Example prompt patterns

**Analysis**

* “Summarize app performance for the last 7 days.”
* “Compare push and email performance for the last 14 days.”
* “Which campaigns drove the most revenue last week?”

**Audience and user investigation**

* “How many users are in the churn-risk segment?”
* “Show the recent events for this user.”
* “List messages sent to this user in the last 3 days.”

**Safe operational requests**

* “Create a push draft for dormant Android users.”
* “Pause the automation named Welcome Flow.”
* “Refresh the count for the VIP segment.”

### How write actions work

Write actions stay controlled.

Your MCP client can only prepare or execute actions that your token scope and panel permissions allow.

{% hint style="warning" %}
Campaign sending always requires a preview first.

If the audience exceeds **100,000 users**, the request is blocked. Netmera returns a panel link instead.
{% endhint %}

#### Built-in safeguards

* Write actions require `mcp:write`.
* Campaign sends require preview and approval.
* All actions follow your panel permissions.
* Large sends are blocked from direct MCP execution.
* All actions are recorded in audit logs.

### Troubleshooting

When something does not work as expected, start with these checks:

1. Confirm the token is still valid.
2. Confirm the token has the right scope.
3. Confirm you connected the correct Netmera app.
4. Confirm your permissions allow the action.

#### Token expired

Request a new token. Token lifetime depends on the token type:

* **JWT** — 30 days
* **OAuth access token** — 8 hours

#### Write scope required

This means the token was created with `mcp:read`. Create a new token with `scope: "mcp:write"` when you need write actions.

#### Cannot access another app

Each token is tied to one Netmera app. Create a separate token for each app you want to use.

#### Send request blocked

This usually means one of these conditions was not met:

* The audience is below **100,000 users**.
* Preview was completed.
* Approval was completed when required.
* Your panel permissions allow the action.

#### User fields are masked

Masking is expected for regulated personal data. Use profile, event, and message history to investigate the issue without exposing PII.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://user.netmera.com/netmera-user-guide/ai-features/netmera-mcp-server/setup-the-netmera-mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.