# Parli auth.md

Você é um agente (ChatGPT, Claude, Cursor ou outro cliente MCP). Este documento explica como pedir acesso ao servidor MCP da Parli em nome de uma pessoa. Com ele, a pessoa cria, testa e ajusta o atendente de IA do WhatsApp dela e conecta o número, conversando com você.

O acesso usa OAuth 2.1 padrão, com autorização de uma pessoa em todos os casos. Não existe chave de API, senha fixa nem credencial estática para agentes. Não existe registro anônimo nem por asserção de identidade (ID-JAG).

## Resumo

| Item | Valor |
| --- | --- |
| Recurso protegido | `https://app.parlichat.com/mcp` |
| Transporte | Streamable HTTP |
| Metadados do recurso (RFC 9728) | `https://app.parlichat.com/.well-known/oauth-protected-resource/mcp` |
| Servidor de autorização (issuer) | `https://app.parlichat.com` |
| Metadados do servidor (RFC 8414) | `https://app.parlichat.com/.well-known/oauth-authorization-server` |
| Registro de cliente (RFC 7591) | `https://app.parlichat.com/oauth/register` |
| Autorização | `https://app.parlichat.com/oauth/authorize` |
| Token | `https://app.parlichat.com/oauth/token` |
| Fluxo | `authorization_code` com PKCE `S256` (obrigatório) e `refresh_token` |
| Escopo | `mcp:use` |
| Envio do token | Cabeçalho `Authorization: Bearer <access_token>` |

## Passo 1: descobrir

Se você chamou `https://app.parlichat.com/mcp` sem token, a resposta 401 já traz o caminho no cabeçalho:

```http
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://app.parlichat.com/.well-known/oauth-protected-resource/mcp"
```

1. Busque os metadados do recurso em `https://app.parlichat.com/.well-known/oauth-protected-resource/mcp`. O campo `authorization_servers` aponta para `https://app.parlichat.com`.
2. Busque os metadados do servidor de autorização em `https://app.parlichat.com/.well-known/oauth-authorization-server`. Confira se o `issuer` é `https://app.parlichat.com`.

Use sempre os endereços que vierem nos metadados. A tabela acima é só referência.

## Passo 2: registrar o cliente

Registre o seu cliente por registro dinâmico (RFC 7591) com um `POST` em `/oauth/register`. O registro é aberto para qualquer cliente MCP e não pede credencial prévia.

Regras para `redirect_uris`:

- `https` em qualquer domínio; ou
- `http` somente em endereço local (`127.0.0.1`, `localhost` ou `[::1]`).

## Passo 3: pedir a autorização da pessoa

Abra `/oauth/authorize` com `response_type=code`, o `client_id` recebido no registro, o `redirect_uri`, `scope=mcp:use`, `resource=https://app.parlichat.com/mcp`, um `state` e um `code_challenge` com `code_challenge_method=S256`.

A pessoa entra na conta da Parli, escolhe a conta e o time a que você vai ter acesso e aprova numa tela de consentimento. Sem essa aprovação não há acesso. Mostre a ela, antes, o que você pretende fazer.

## Passo 4: trocar o código pelo token

Envie o `code` e o `code_verifier` para `/oauth/token` com `grant_type=authorization_code`. O `access_token` vale uma hora. Quando ele vencer, use o `refresh_token` com `grant_type=refresh_token`.

## Passo 5: usar o servidor MCP

Conecte em `https://app.parlichat.com/mcp` com o cabeçalho `Authorization: Bearer <access_token>`. Liste as ferramentas disponíveis pelo próprio protocolo (`tools/list`): elas mudam com o tempo e dependem da conta.

## Como o acesso é revogado

A pessoa pode encerrar o acesso a qualquer momento de duas formas:

- removendo o aplicativo da Parli nas configurações do assistente que ela usa; ou
- desconectando o assistente dentro da Parli.

Depois disso, o token e o `refresh_token` deixam de funcionar. Peça uma nova autorização, começando do passo 3.

## O que não existe

- Chave de API ou credencial fixa para agentes.
- OpenID Connect (`openid-configuration`) e JWKS.
- Endereços de reivindicação (`claim_uri`) ou de revogação próprios para agentes.
- Bloco `agent_auth` nos metadados do servidor de autorização.

Mais sobre a Parli: https://parlichat.com e https://parlichat.com/llms.txt
