# Autenticación

> Qué token recibe el servidor MCP, qué permiso necesita, dónde va el token en cada tipo de conexión y cómo cuidarlo.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/mcp/authentication/

Para agentes: Cómo se autentica el servidor MCP de Sypnia: un token de API (sps_) con el permiso read, enviado como encabezado Authorization Bearer al servidor remoto o como SYPNIA_API_TOKEN al local; un token es un proyecto; sin OAuth al lanzar.

**\[Motor]** **\[Nube]** El servidor MCP usa la misma credencial que la API HTTP: un token de API. No tiene cuenta ni contraseña aparte, y no abre ninguna ventana para iniciar sesión.

## El token

|                      |                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tipo                 | Token de API, `sps_` y 40 caracteres                                                                                                                                                                             |
| Permiso que necesita | `read`. Nada más                                                                                                                                                                                                 |
| A qué llega          | A un proyecto. Un token pertenece exactamente a uno                                                                                                                                                              |
| Dónde crearlo        | Sypnia Cloud: en la app, en los ajustes del proyecto. Alojamiento propio: `sypnia token create --name "Mi agente" --scopes read`, o [`POST /v1/tokens`](https://docs.sypnia.com/es/api/projects-keys-and-tokens) |

`read` basta para las diez herramientas, incluida `resolve_problem`: marcar un problema como resuelto es una de las marcas reversibles que un token `read` puede hacer. Mira [los permisos](https://docs.sypnia.com/es/api/overview-and-authentication).

No le des a un agente un token con `admin`. El servidor no lo usa, y el token que queda en la configuración de tu agente se podría usar directo contra la API para revocar llaves o borrar datos. Tampoco uses el token raíz de un motor alojado por ti.

> **Nota: Un token para cada agente**
>
> Ponle al token el nombre de quien lo usa: «Cursor, portátil de Ana». El nombre aparece en cada problema que el agente resuelve (`resolved_by: mcp:Cursor, portátil de Ana`), y puedes revocar un agente sin tocar los demás.

## Dónde va el token

| Conexión                                  | Cómo viaja el token                                                                                              |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Servidor remoto (Sypnia Cloud o tu motor) | En el encabezado `Authorization` de cada petición: `Authorization: Bearer sps_…`                                 |
| Servidor local (`@sypnia/mcp`)            | En la variable de entorno `SYPNIA_API_TOKEN`. El servidor local lo envía después a la API en el mismo encabezado |

El servidor remoto no guarda el token. Lo comprueba con el motor en cada petición y lo usa para leer tu proyecto, igual que lo haría la API.

## Mantenlo fuera de tu repositorio

Un token en un archivo subido al repositorio es un token filtrado. Los dos clientes pueden leerlo del entorno.

**Claude Code**

En un `.mcp.json` compartido, escribe `${SYPNIA_API_TOKEN}` y define la variable en la máquina de cada persona:

`.mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "type": "http",
      "url": "https://mcp.sypnia.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

Un servidor que agregas para ti, sin `--scope project`, se guarda en tus propios ajustes, no en el repositorio.

**Cursor**

En `.cursor/mcp.json`, escribe `${env:SYPNIA_API_TOKEN}`:

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "url": "https://mcp.sypnia.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

**Any agent**

Si tu cliente no puede leer el entorno desde su configuración, deja ese archivo fuera del control de versiones, o usa el servidor local y define `SYPNIA_API_TOKEN` en el entorno con el que el cliente lo arranca.

## Varios proyectos

Un token es un proyecto, así que una conexión es un proyecto. Para trabajar con dos proyectos, agrega el servidor dos veces con dos nombres, cada uno con su token:

```bash
claude mcp add --transport http sypnia-shop \
  https://mcp.sypnia.com/mcp \
  --header "Authorization: Bearer YOUR_SHOP_TOKEN"

claude mcp add --transport http sypnia-blog \
  https://mcp.sypnia.com/mcp \
  --header "Authorization: Bearer YOUR_BLOG_TOKEN"
```

Tu agente ve entonces `sypnia-shop.problems` y `sypnia-blog.problems`, y no puede confundirlos.

## Cambiar o revocar un token

1. Crea un token nuevo.
2. Ponlo en la configuración y reinicia el cliente.
3. Revoca el anterior: en la app, con `sypnia token revoke <id del token>`, o con `DELETE /v1/tokens/{token_id}`.

Un token revocado se rechaza en menos de un minuto. Si un token pudo haberse filtrado, revócalo primero.

## Errores

| El servidor responde   | Qué significa                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `401 unauthorized`     | No hay token, o es desconocido, revocado o vencido                                    |
| `403 wrong_credential` | Se envió una llave de ingesta (`spk_…`). El servidor MCP solo recibe tokens de API    |
| `403 forbidden`        | El token no tiene el permiso `read`                                                   |
| `429 rate_limited`     | El token hizo más de 600 peticiones en un minuto. El agente debe esperar y reintentar |

## No al lanzar

Iniciar sesión por el navegador (OAuth), donde el cliente abre una página y tú apruebas, no está disponible al lanzar. El token en el encabezado es la única forma.
