# Conectar

> Conecta Claude Code, Cursor o cualquier otro cliente MCP al servidor MCP de Sypnia, remoto o local, con el comando o el fragmento exacto para cada uno.

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/connect/

Para agentes: Comandos y fragmentos exactos para conectar el servidor MCP de Sypnia: Claude Code (claude mcp add), Cursor (.cursor/mcp.json), otros clientes; remoto por Streamable HTTP en https://mcp.sypnia.com/mcp, alojado por ti en <URL base>/mcp, local por stdio con npx @sypnia/mcp.

**\[Motor]** **\[Nube]** Esta página es para quien usa un agente de código que habla MCP.

**Al final tendrás:** tu agente de código conectado a Sypnia, respondiendo «¿qué está fallando en producción?» con datos reales de tu proyecto.

**Antes de empezar** necesitas un token de API con el permiso `read`. Créalo en la app (Sypnia Cloud) o con `sypnia token create --name "Mi agente" --scopes read` (alojamiento propio). Mira [Autenticación](https://docs.sypnia.com/es/mcp/authentication).

## El camino corto

**Claude Code**

1. Agrega las skills de Sypnia:
   ```bash
   claude plugin marketplace add sypnia/skills
   claude plugin install sypnia@sypnia
   ```
2. Conecta el servidor MCP:
   ```bash
   claude mcp add --transport http sypnia \
     https://mcp.sypnia.com/mcp \
     --header "Authorization: Bearer YOUR_API_TOKEN"
   ```

Luego dile: «Configura Sypnia en este proyecto».

**Cursor**

1. Agrega las skills de Sypnia: En Cursor, abre **Customize**, elige **From GitHub Repository** e importa `sypnia/skills`.
2. Conecta el servidor MCP:

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

Luego dile: «Configura Sypnia en este proyecto».

**Any agent**

1. Pega este prompt:
   ```text
   Lee https://docs.sypnia.com/es/llms.txt y sigue la guía de inicio rápido a la que apunta. Agrega Sypnia a este proyecto: instala @sypnia/browser, llama a init() con la llave de mi proyecto (pídemela) y dime cómo comprobar que llegó la primera sesión.
   ```

Un agente sin skills ni MCP igual puede leer todas las páginas: cada una es Markdown plano en su dirección más `.md`.

El resto de la página es lo mismo, completo: cada cliente, un motor alojado por ti y el servidor local.

## Cuál servidor

Hay tres formas de llegar a las mismas diez herramientas. Elige una.

| Servidor                  | Dirección                            | Úsalo cuando                                                                                                             |
| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Remoto, Sypnia Cloud**  | `https://mcp.sypnia.com/mcp`         | Tu proyecto está en Sypnia Cloud. No hay nada que instalar                                                               |
| **Remoto, tu motor**      | `<tu URL base>/mcp`                  | Alojas tú el motor. El motor lo sirve junto a la API                                                                     |
| **Local** (`@sypnia/mcp`) | Un programa en tu máquina, por stdio | Tu cliente solo soporta stdio, o tu motor no es alcanzable desde donde se conecta el cliente. Llama a la API HTTP por ti |

Los servidores remotos hablan Streamable HTTP y reciben el token en el encabezado `Authorization`. El local necesita Node.js 20 o posterior y toma el token de una variable de entorno.

## Conecta tu cliente

**Claude Code**

### 1. Agrega el servidor

Corre uno de estos en el directorio de tu proyecto.

Sypnia Cloud:

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

Un motor alojado por ti:

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

El servidor local:

```bash
claude mcp add --env SYPNIA_API_TOKEN=YOUR_API_TOKEN --transport stdio sypnia \
  -- npx -y @sypnia/mcp
```

Para un motor alojado por ti con el servidor local, agrega `--env SYPNIA_BASE_URL=https://sypnia.example.com` antes de `--transport`.

**Deberías ver:**Claude Code confirma que agregó el servidor `sypnia`.

### 2. Compruébalo

```bash
claude mcp list
```

**Deberías ver:**`sypnia` aparece como conectado. Dentro de una sesión, `/mcp` muestra el servidor y sus herramientas.

Por defecto el servidor se agrega para ti, en este proyecto. Agrega `--scope user` para tenerlo en todos los proyectos, o `--scope project` para compartirlo con tu equipo por medio de un archivo `.mcp.json` en la raíz del repositorio. En ese archivo, toma el token del entorno para que nunca quede en un commit:

`.mcp.json`

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

Para quitar el servidor: `claude mcp remove sypnia`.

**Cursor**

### 1. Escribe la configuración

Crea `.cursor/mcp.json` en tu proyecto, o `~/.cursor/mcp.json` para tener Sypnia en todos los proyectos.

Sypnia Cloud:

`.cursor/mcp.json`

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

Un motor alojado por ti: lo mismo, con `"url": "https://sypnia.example.com/mcp"`.

El servidor local:

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "command": "npx",
      "args": ["-y", "@sypnia/mcp"],
      "env": {
        "SYPNIA_API_TOKEN": "${env:SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

Para un motor alojado por ti con el servidor local, agrega `"SYPNIA_BASE_URL": "https://sypnia.example.com"` a `env`.

### 2. Define el token

`${env:SYPNIA_API_TOKEN}` lee el token de tu entorno, así que el archivo se puede subir al repositorio sin riesgo. Define la variable donde arranca Cursor, por ejemplo en el perfil de tu terminal:

```bash
export SYPNIA_API_TOKEN=YOUR_API_TOKEN
```

Luego reinicia Cursor.

### 3. Compruébalo

Abre **Customize** en la barra lateral de Cursor.

**Deberías ver:**`sypnia` aparece con sus herramientas y su interruptor encendido. El mismo interruptor apaga el servidor sin quitarlo.

**Any agent**

Cualquier cliente MCP se puede conectar. Dale uno de estos, en la forma que pida su configuración.

**Un servidor remoto** (Streamable HTTP):

| Ajuste     | Valor                                                                     |
| ---------- | ------------------------------------------------------------------------- |
| URL        | `https://mcp.sypnia.com/mcp`, o `<tu URL base>/mcp` si alojas tú el motor |
| Encabezado | `Authorization: Bearer YOUR_API_TOKEN`                                    |

**Un servidor local** (stdio):

| Ajuste     | Valor                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------ |
| Comando    | `npx`                                                                                      |
| Argumentos | `-y @sypnia/mcp`                                                                           |
| Entorno    | `SYPNIA_API_TOKEN=YOUR_API_TOKEN`, y `SYPNIA_BASE_URL=<tu URL base>` si alojas tú el motor |

Muchos clientes leen un archivo JSON con esta forma:

```json
{
  "mcpServers": {
    "sypnia": {
      "command": "npx",
      "args": ["-y", "@sypnia/mcp"],
      "env": { "SYPNIA_API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}
```

Un cliente que solo soporta el transporte anterior, HTTP+SSE, no puede llegar al servidor remoto: usa el local.

Un agente sin soporte de MCP también puede usar Sypnia: copia en él [el prompt](https://docs.sypnia.com/es/agent/the-prompt) de un problema.

## Comprueba que funciona

Pregúntale a tu agente:

```text
¿Qué está fallando en producción?
```

**Deberías ver:**

El agente llama a la herramienta `health` (tu cliente puede pedirte permiso) y responde con los datos de tu proyecto. Si no hay nada mal, lo dice. Los clientes muestran la llamada bajo el nombre del servidor: `sypnia.health`, `sypnia:health` o `mcp__sypnia__health`.

## Opciones del servidor local

`@sypnia/mcp` lee estas. Las opciones de línea de comandos ganan sobre las variables.

| Variable               | Opción                  | Por defecto              | Qué es                                          |
| ---------------------- | ----------------------- | ------------------------ | ----------------------------------------------- |
| `SYPNIA_API_TOKEN`     | Ninguna                 | Ninguno, obligatoria     | El token de API                                 |
| `SYPNIA_BASE_URL`      | `--base-url <url>`      | `https://api.sypnia.com` | La URL base de tu motor, sin `/v1`              |
| `SYPNIA_PROJECT`       | `--project <id o slug>` | Ninguno                  | Solo con una credencial que ve varios proyectos |
| `SYPNIA_MCP_READ_ONLY` | `--read-only`           | `false`                  | `true` quita `resolve_problem`                  |

## Cuando no funciona

| Qué ves                                                    | Por qué                                              | Qué hacer                                                                                                                        |
| ---------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401 unauthorized`                                         | Falta el token, está mal escrito, revocado o vencido | Crea un token nuevo y actualiza la configuración. Revisa que haya exactamente un espacio después de `Bearer`                     |
| El servidor conecta y no lista herramientas                | El cliente habla con la dirección equivocada         | La URL debe terminar en `/mcp`                                                                                                   |
| `403 wrong_credential`                                     | Usaste una llave de ingesta (`spk_…`)                | Usa un token de API (`sps_…`)                                                                                                    |
| Funciona desde tu portátil y no desde un agente en la nube | Tu motor no es alcanzable desde allá                 | Expón el motor, o corre el servidor local donde sí lo alcance                                                                    |
| Falta `resolve_problem`                                    | El servidor está en solo lectura                     | Mira [Seguridad](https://docs.sypnia.com/es/mcp/security)                                                                        |
| Las respuestas son de otra app                             | El token es de otro proyecto                         | Cada token es de un proyecto. Agrega un servidor por proyecto, cada uno con su nombre, por ejemplo `sypnia-shop` y `sypnia-blog` |

## Sigue con

- [Skills](https://docs.sypnia.com/es/mcp/skills): deja que tu agente configure Sypnia y arregle problemas siempre de la misma forma.
- [Ejemplos](https://docs.sypnia.com/es/mcp/examples): tres sesiones, de la pregunta al arreglo.
- [Referencia de herramientas](https://docs.sypnia.com/es/mcp/tools-reference): cada herramienta y lo que devuelve.
