# Sentl MCP

Sentl MCP server: lets an AI assistant read an organization's
projects and reputation analyses and, with the right permissions, start
analyses and update projects.

Full user guide: https://app.sentl.ai/mcp/setup

## Connection details

| Field | Value |
|---|---|
| Server name | Sentl MCP |
| Endpoint | `https://app.sentl.ai/mcp` |
| Transport | Remote HTTP (Streamable HTTP). It is not a local stdio server. |
| Authentication | OAuth 2.1 with PKCE, or Bearer token |
| OAuth scope | `mcp:use` |

## Connecting via OAuth (recommended)

No token to manage. The endpoint publishes discovery metadata, so a client that
follows the MCP spec configures itself:

- `GET /.well-known/oauth-protected-resource` (RFC 9728) points to the authorization server
- `GET /.well-known/oauth-authorization-server` (RFC 8414) exposes the endpoints
- `POST /oauth/register` (RFC 7591) allows Dynamic Client Registration

On a request without a valid token the endpoint returns `401` with a
`WWW-Authenticate` header containing `resource_metadata`, the starting point for discovery.

Login and consent happen in the browser and are completed by the user: the
consent screen lists all of the user's organizations, with their role in each,
and the connection covers all of them. There is no organization to choose. This
is not a step an assistant can take on their behalf.

DCR is only allowed for the official clients' domains. A client on an
unexpected domain must use the token method.

Command-line clients, one command per client (there is no common syntax):

```
# Claude Code
claude mcp add --transport http sentl-mcp https://app.sentl.ai/mcp
# Codex CLI
codex mcp add sentl-mcp --url https://app.sentl.ai/mcp
# Gemini CLI
gemini mcp add --transport http sentl-mcp https://app.sentl.ai/mcp
# VS Code
code --add-mcp '{"name":"sentl-mcp","type":"http","url":"https://app.sentl.ai/mcp"}'
```

The command registers the server; authorization happens on first use (in
Claude Code with `/mcp`). Other clients use the JSON configuration below.

## Connecting via Bearer token

For clients without OAuth. The user creates the token in **Integrations → API
Tokens** (user menu) inside Sentl; an assistant cannot generate it. The token is
personal and works across all of the user's organizations.

```
Authorization: Bearer <TOKEN_SENTL>
```

JSON configuration, if the client requires it:

```json
{
    "mcpServers": {
        "sentl-mcp": {
            "type": "http",
            "url": "https://app.sentl.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${SENTL_MCP_TOKEN}"
            }
        }
    }
}
```

## Scope of a connection

Each connection applies to **all of the user's organizations**, and in each one
with the permissions of the user's **role** there, checked on every request. The same
connection can therefore write in one organization and be read-only in
another.

The organization doesn't need to be specified when the request already names a
project or a run: it is derived from that. It is only needed to **create** a project,
and as an optional filter on the list. Use `list-organizations` for the allowed slugs.

## Available tools

Read, for all roles (including User):

- list the available AI research models
- list the organizations accessible with your role
- list the projects across all organizations with their latest analysis
- read a project's details: dimensions (archived ones included), questions, grading rubrics
- get a project's edit link in Sentl
- list a project's analyses (runs) with scores and dates
- read an analysis's results: model responses and judgments/sentiment

Write, Owner and Admin only:

- start a new manual analysis on a project
- create or update a project (name, frequency, rounds, models, activation). Each
  round repeats every question in the same run, so the run's cost is multiplied
  by the number of rounds
- update questions and evaluation dimensions, and archive or restore a dimension

The write tools are hidden only when the user is Owner or Admin in **no**
organization. If they are in at least one, the tools are listed, and a call on a
project of an organization where the user is only User is refused with a tool error.

New projects are created **paused**: saving a project does not start
an analysis. It needs a manual start, or activation for scheduled analyses.

## Errors

| Code | Meaning |
|---|---|
| 401 | Token missing, expired or invalid. Repeat the OAuth flow or check the header. An OAuth login unused for 30 days must be repeated. |
| 405 | The endpoint is receiving a generic HTTP request instead of an MCP session. |

Refusals on a specific action are not HTTP errors: they come back as a **tool
error** whose message explains the reason. Report it to the user as is:

- insufficient permissions: the user's role in that project's organization is read-only;
- insufficient credits: the message states the credits required and available, and
  the organization whose credits need topping up;
- subscription not active: the organization's subscription must be reactivated first;
- project or run not found: it does not exist, or it belongs to an organization the
  user is not a member of.

## Revocation

Both pages are personal (not per organization), under **Integrations** in the
user menu:

- OAuth connections: **Connected apps**
- tokens: **API Tokens**
