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.
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 |
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.
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.
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:
{
"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}:
{
"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:
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
- Crea un token nuevo.
- Ponlo en la configuración y reinicia el cliente.
- Revoca el anterior: en la app, con
sypnia token revoke <id del token>, o conDELETE /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.